Errors

The standard error envelope, request IDs, error codes, and retry guidance.

API errors use one standard envelope:

{
  "status": "error",
  "code": "validation_error",
  "message": "Validation failed",
  "request_id": "F7qLx0e8hAA=",
  "details": {
    "status": "must be one of draft, approved, void"
  }
}

request_id is echoed from x-request-id when available. Include it in support requests and logs.

Common codes

HTTP	Code	Retry?	Meaning
400	`invalid_idempotency_key`	No	`Idempotency-Key` is blank, too long, or repeated in headers.
401	`unauthorized`	After fixing auth	Missing, expired, revoked, or invalid bearer token.
403	`forbidden`	No	Token is valid but lacks the required scope or policy permission.
404	`not_found`	No	The resource does not exist in the authenticated tenant. Cross-tenant lookups also return 404.
409	`conflict`	Usually no	Resource state does not allow the requested transition.
409	`idempotency_key_conflict`	No	The key was already used for a different request fingerprint.
409	`idempotency_key_in_progress`	Yes	The first request for this idempotency key has not completed.
422	`validation_error`	After fixing payload	Request body or query parameters failed validation.
422	`period_closed`	After period unlock	The accounting period is locked for the requested mutation.
429	`rate_limited`	Yes	Retry after the `retry-after` header value.
500	`server_error`	Yes	Unexpected server failure.
500	`workflow_crashed`	Yes	A workflow raised unexpectedly.

Some extension and deployment endpoints return endpoint-specific codes such as deploy_failed, dev_deploy_failed, rollback_failed, promote_failed, and hook_error. They still use the same envelope.

Retry guidance

Retry:

429 rate_limited after retry-after.
409 idempotency_key_in_progress with the same request and same key.
5xx failures with an Idempotency-Key on POST requests.

Do not retry unchanged:

401 unauthorized.
403 forbidden.
404 not_found.
409 idempotency_key_conflict.
422 validation_error or 422 period_closed.

Success envelopes

Public resource endpoints use record and list envelopes — status and message at the top level are reserved for error envelopes and legacy compatibility responses. Record reads and mutations return {id, object, data}; deletes and voids return a deleted-object envelope with deleted: true (and voided: true where appropriate); lists return {object: "list", data, pagination}.

← Versioning

Pagination & filters →