Error handling

Treat every non-2xx response as a failed request. Log the HTTP status, response body, and X-Request-Id.

Error envelope

Canonical API errors use this shape:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_pagination",
    "message": "limit must be between 1 and 100",
    "param": "limit",
    "request_id": "4f4f5fc4-6a43-4f42-a970-3df1231fef91",
    "doc_url": "/docs/api/errors#invalid_pagination"
  }
}

param and doc_url may be omitted. request_id matches the X-Request-Id response header.

Status handling

• 400 means the request shape or input value is invalid.
• 401 means authentication failed or required auth context is missing.
• 403 means the caller is authenticated but not allowed to perform the action.
• 404 means the resource was not found in the caller's scope.
• 409 means the requested state change conflicts with current data.
• 422 means the request was understood but cannot be applied as submitted.
• 429 means the caller or upstream provider is rate-limited.
• 5xx means the API or an upstream dependency failed.

Retry only operations that are safe to repeat. For writes, use the endpoint's documented idempotency behavior before retrying.