Errors & Request IDs

{
  "error": {
    "code": "validation_failed",
    "message": "The request could not be processed.",
    "request_id": "req_EXAMPLE",
    "details": []
  }
}

Branch on the stable code, not message text. Preserve X-Request-Id or error.request_id when contacting support.

Status	Client action
401	Refresh or reauthorize once; do not loop
403 / 404	Reconcile authority or identity; do not enumerate
409	Reconcile idempotency or resource state
422	Correct domain input
429	Honor Retry-After, then back off
5xx / network ambiguity	Bounded backoff; retry writes with the same idempotency key

OAuth endpoints return OAuth protocol errors and do not use this envelope.