Errors and retries

HTTP status codes, retryable failures, and request correlation.

Envelope

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope for this operation.",
    "param": null,
    "retryable": false,
    "documentation_url": "/help/errors"
  },
  "request_id": "req_01j…"
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope for this operation.",
    "param": null,
    "retryable": false,
    "documentation_url": "/help/errors"
  },
  "request_id": "req_01j…"
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope for this operation.",
    "param": null,
    "retryable": false,
    "documentation_url": "/help/errors"
  },
  "request_id": "req_01j…"
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope for this operation.",
    "param": null,
    "retryable": false,
    "documentation_url": "/help/errors"
  },
  "request_id": "req_01j…"
}

Error catalogue

The following error codes are part of the public contract:

Code	HTTP	Retryable	Typical cause
`invalid_request`	400	no	Wrong content type, bad cursor, over-long `Idempotency-Key`, bad method on `/mcp`
`invalid_json`	400	no	Body is not JSON
`unknown_field`	400	no	Field not in the contract (`param` names it)
`idempotency_key_required`	400	no	Write without `Idempotency-Key`
`authentication_required`	401	no	No bearer, or key sent in query/cookie
`invalid_api_key`	401	no	Unknown, malformed or disabled key; invalid session
`api_key_revoked`	401	no	Key revoked
`api_key_expired`	401	no	Key past `expires_at`
`surface_not_allowed`	403	no	Key not allowed on API/MCP; session token on MCP; disallowed browser origin on MCP
`insufficient_scope`	403	no	Missing scope
`brand_access_denied`	403	no	Reserved; brand checks currently answer `404` to prevent enumeration
`api_plan_required`	403	no	Owner is not on Scale/Enterprise
`feature_not_enabled`	403	no	Not enrolled, beta scope not allowed, flag off, brand/destination frozen, account locked, no entitlement, plan feature missing
`resource_not_found`	404	no	Unknown or not accessible with this key; unknown route
`integration_not_ready`	409	yes	Destination not healthy
`invalid_state`	409	no	Content not publishable, preview expired/mismatched/changed, stale edit, only-active-keys rules
`idempotency_key_reused`	409	see `retryable`	Different request with the same key (no), or original still in progress (yes)
`job_not_cancellable`	409	no	Job not queued any more
`payload_too_large`	413	no	Body > 1 MB (draft body > 256 KB)
`validation_failed`	422	no	Invalid value; `param` names it
`rate_limited`	429	yes	Per-minute limit (or Local 24 h run limit)
`quota_exceeded`	429	yes¹	Daily requests or monthly credits exhausted; also max active keys (¹non-retryable) and Local location cap
`concurrency_limit_exceeded`	429	yes	Too many jobs in progress
`operation_failed`	500	no	Unexpected failure — contact support with `request_id`
`provider_rejected`	502	no	Destination rejected the operation
`upstream_unavailable`	503	yes	Database, Redis, queue or provider unreachable; MCP tool timeout
`service_unavailable`	503	yes	Surface disabled by operators

Connectivity failures (DNS, refused, reset, timeout) towards Postgres or Redis are always reported as 503 upstream_unavailable with Retry-After: 5, never as 500.

Job and operation failure codes

failure.code on jobs and publishing operations comes from a keyword mapping of worker/provider errors. The raw text is never stored or returned:

`failure.code`	Retryable	Meaning
`authorization_context_invalid`	no	Worker could not verify the signed context (secret mismatch or tampering)
`feature_disabled`	no	Kill switch or destination freeze flipped while queued
`feature_not_enabled`	no	Owner lost entitlement after admission
`generation_failed`	no	Generated content failed quality checks
`provider_rejected`	no	Destination rejected (auth etc.)
`upstream_unavailable`	yes	Timeout / 5xx / connection error
`operation_failed`	no	Anything else, including orphaned jobs (no trace after 10 min)

API & MCP overview

Get help