Errors & retries

Every error has a code, a message, and a request ID. Handle the uncertainty as carefully as the happy path.

A consistent error format

{
  "error": {
    "code": "validation_error",
    "message": "Choose at least one account."
  },
  "request_id": "req_example"
}

Use the stable code for program logic. The message is intended for diagnosis. Store the request ID with your own logs; do not log bearer keys or connected-account credentials.

Idempotency is part of the request

Choose a unique idempotency key for each logical post. Use that same key and the same payload after a timeout. Reusing a key with a different payload is a conflict; use a new key only for a genuinely new post.

try {
  await castrook.posts.create(payload, {
    idempotencyKey: 'campaign-42-post-7',
  });
} catch (error) {
  if (error instanceof CastrookError) {
    console.error(error.code, error.requestId);
  }
}

An uncertain result needs inspection

A platform can accept a write before a network timeout. Castrook does not blindly repeat an ambiguous publish. Inspect the target error and the platform account before creating a replacement. The same caution applies to comment replies, which are not idempotent.

Retry safe operations

The TypeScript client retries GET requests and posts with idempotency keys on transport failures, 429, and 5xx. It respects a bounded Retry-After delay and uses a request timeout. It does not automatically repeat comment replies.