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
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
AUTH_INVALID | 401 | No | Credential, token, or signature is invalid for requested operation. |
POLICY_DENIED | 403 | No | Policy evaluation denied the execution or session action. |
RISK_EXCEEDED | 403 | No | Risk control exceeded configured threshold; manual override needed. |
ROUTE_UNAVAILABLE | 503 | Yes | Requested provider/model/region route is unavailable. |
TOOL_BLOCKED | 403 | No | Requested tool invocation is blocked by governance policy. |
RATE_LIMITED | 429 | Yes | Rate limit exceeded for workspace, principal, or API key. |
TIMEOUT | 408 | Yes | Execution or control path exceeded timeout budget. |
INTERNAL | 500 | Depends | Unexpected server-side failure; inspect requestId and retry policy. |