Errors

Error Shape

{
  "error": {
    "code": "policy.validation_failed",
    "message": "Policy 'vendor-tier' failed schema validation.",
    "retryable": false,
    "trace_id": "b7ad...e2"
  }
}

Error Codes

• auth.unauthorized — missing or invalid token.
• auth.forbidden — token lacks the required scope.
• resource.not_found — the resource does not exist in this tenant.
• policy.validation_failed — a policy or config failed validation.
• rate.limited — request exceeded the rate limit.

Retryable Errors

Each error carries a retryable flag. Transient conditions such as rate.limited are safe to retry with backoff; validation and authorization errors are not.

Handling Errors

Branch on code, never on message. Messages are human-oriented and may change; codes are part of the stable contract and include a trace_id to correlate with logs.