Skip to main content

Errors and retries

Error responses use a stable JSON envelope:

{
  "code": "BAD_REQUEST",
  "message": "Invalid request",
  "requestId": "req-123"
}
  • code is a stable machine-readable error code.
  • message is safe to display or log.
  • requestId identifies the request for support and troubleshooting.

Handle behavior by HTTP status and code, not by matching message text.

Retry signals​

A 202 Accepted response means processing is not terminal. A retryable 409 Conflict, 429 Too Many Requests, or 503 Service Unavailable can include Retry-After. Wait at least the indicated number of seconds before polling or retrying.

Do not automatically retry validation, authentication, permission, or semantic errors. When retrying an idempotent create operation, send the original Idempotency-Key and unchanged request.