Errors and retries

Read an error

Errors use a JSON envelope:

{
  "error": {
    "code": "example.code",
    "message": "A description of the problem"
  }
}

Some errors include details. Log the HTTP status, error code, and X-Request-Id response header. Exclude API keys and customer message bodies from logs unless your own data policy requires them.

Status	What to do
`400`	Correct the input; check required fields and parameter formats
`401`	Check authentication, expiry, and revocation
`403`	Check permissions and connection restrictions
`404`	Verify the resource ID belongs to the key’s workspace
`409`	Inspect the conflict; do not blindly retry a changed request
`429`	Respect `Retry-After` and reduce concurrency
`5xx`	Retry eligible requests with exponential backoff and jitter

Use idempotency for supported writes

Endpoints that document Idempotency-Key can protect retries against duplicate writes. Generate one unique key per logical action and keep it stable across retries of that same action.

Idempotency-Key: 47d7ac31-8e9d-4db5-b6e4-0aa4eec09556

Retry with the same method, endpoint, query, body, and key. Do not reuse the key for a different action. A replay may include Idempotency-Replayed: true. Conflicting payloads or an in-progress request can return 409. If a write times out, it may already have completed. Use the original idempotency key when the endpoint supports it; otherwise inspect the resource before repeating the operation.

Retry Help Center proposals

Authoring writes require an idempotency key. MCP proposal tools take it as idempotencyKey; HTTP requests use the header. Use 8–128 printable, non-space ASCII characters. For a revision conflict, fetch the latest article and ask for a new review decision. Do not silently overwrite newer content. An uncertain network result should be retried only with identical arguments and the original key.

Get started

API essentials

Build an integration

Errors and retries

Read an error

Use idempotency for supported writes

Retry Help Center proposals

​Read an error

​Use idempotency for supported writes

​Retry Help Center proposals

Read an error

Use idempotency for supported writes

Retry Help Center proposals