Canonical Envelope

Error envelope

{
  "ok": false,
  "data": null,
  "meta": {
    "requestId": "req_123",
    "sessionId": "sess_123",
    "executionId": "exec_123",
    "timingMs": {
      "total": 42,
      "policy": 12,
      "route": 8,
      "tool": 10
    }
  },
  "error": {
    "code": "POLICY_DENIED",
    "message": "Policy denied execution.",
    "status": 403,
    "retryable": false,
    "details": {
      "rule": "pii_block"
    }
  }
}

Stable Error Codes

CodeHTTPRetryableMeaning
AUTH_INVALID401NoCredential, token, or signature is invalid for requested operation.
POLICY_DENIED403NoPolicy evaluation denied the execution or session action.
RISK_EXCEEDED403NoRisk control exceeded configured threshold; manual override needed.
ROUTE_UNAVAILABLE503YesRequested provider/model/region route is unavailable.
TOOL_BLOCKED403NoRequested tool invocation is blocked by governance policy.
RATE_LIMITED429YesRate limit exceeded for workspace, principal, or API key.
TIMEOUT408YesExecution or control path exceeded timeout budget.
INTERNAL500DependsUnexpected server-side failure; inspect requestId and retry policy.