Error handling - PostlyBee

PostlyBee uses conventional HTTP status codes. Every error body has the same shape, with a stable code you can branch on:

{
  "statusCode": 402,
  "code": "quota_exceeded",
  "message": "The workspace has reached its monthly post limit."
}

Status codes

Status	Meaning	Recommended action
`200`	Request completed.	Read the response body.
`201`	Resource created or operation accepted.	Store returned IDs.
`400`	Invalid fields or unsupported operation.	Correct the request before retrying.
`401`	Missing, expired, revoked, or invalid token.	Replace or rotate the API token.
`402`	Workspace plan does not allow the operation.	Review workspace billing and limits.
`403`	Missing scope or unavailable workspace.	Review token scopes, allowlist, and membership.
`404`	Resource not found in this workspace.	Check the ID and workspace.
`409`	Conflict with an existing resource or key.	Read `code`; do not retry blindly.
`429`	Hourly API limit exceeded.	Wait for `Retry-After` before retrying.
`500`	Unexpected server failure.	Retry with backoff and contact support if persistent.

Error codes

`code`	Meaning
`invalid_request`	A field is missing or invalid.
`unauthorized`	The bearer token is missing, invalid, expired, or revoked.
`forbidden`	The workspace is not available to this token.
`insufficient_scope`	The token lacks a scope; `requiredScopes` lists them.
`not_found`	The resource does not exist in this workspace.
`quota_exceeded`	The workspace reached its monthly post limit.
`plan_limit`	Another plan limit was reached, for example webhooks or channels.
`integration_disconnected`	The selected account is disabled or must be reconnected.
`external_id_conflict`	`externalId` is already used by a live post; `postId` names it.
`idempotency_key_reused`	The `Idempotency-Key` was used with a different body.
`idempotency_in_progress`	The first request with this `Idempotency-Key` is still running.
`webhook_disabled`	The webhook is paused; resume it before sending a test event.
`rate_limited`	The hourly API limit was exceeded.
`internal_error`	Unexpected server failure.

Validation errors

Validation errors usually include an array of field messages:

{
  "statusCode": 400,
  "code": "invalid_request",
  "message": ["date must be a valid ISO 8601 date string"]
}

Business-rule errors may use a single string in message instead.

Retry strategy

Retry only transient failures such as 429 and 5xx. Use exponential backoff with jitter, respect Retry-After, and cap the number of attempts. Do not automatically retry 400, 401, or 403 responses.

const retryable = response.status === 429 || response.status >= 500;

if (retryable) {
  const retryAfter = Number(response.headers.get('retry-after') || 1);
  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
}

Log a request identifier, HTTP method, endpoint, status code, and response message. Never log the Authorization header or full API token.

Last modified on August 26, 2026