Error codes
All API errors use the ErrorResponse envelope:
{
"error": {
"code": "invalid_request",
"message": "model is required",
"type": "invalid_request_error",
"param": "model",
"request_id": "req_01HXYZ"
}
}code— one of the stable values in the table below (ErrorCodeenum in
openapi.yaml). Clients should branch on code, not on message.
type— the coarse category, stable per code:invalid_request_errorfor
invalid_request, validation_error and csrf_invalid; authentication_error for unauthorized; permission_error for forbidden; not_found_error for not_found; conflict_error for conflict; rate_limit_error for rate_limit_exceeded; payment_error for budget_exceeded; provider_error for provider_error; server_error for internal_error and secrets_unavailable.
message— human-readable description; may change without notice.type— coarse error category (for OpenAI-compatible clients).param— offending request field, when applicable, otherwisenull.request_id— correlation id to quote in support requests, otherwisenull.
Codes
| Code | HTTP status | Meaning | Typical cause |
|---|---|---|---|
invalid_request | 400 | The request is malformed or missing required data. | Unknown field, missing body, bad JSON. |
validation_error | 400 | The request failed schema/semantic validation. | limit out of range, invalid role, bad email. |
unauthorized | 401 | Authentication is missing or invalid. | Missing/expired session cookie or API key. |
forbidden | 403 | Authenticated but not allowed to perform the action. | Non-admin calling an /admin/* route. |
not_found | 404 | The referenced resource does not exist. | Unknown id, workspace, key, or model. |
conflict | 409 | The request conflicts with current state. | Duplicate org slug or provider type. |
budget_exceeded | 402 | The key or workspace budget is exhausted. | Monthly limit_usd reached. |
rate_limit_exceeded | 429 | Per-key request/token rate limit hit. | Exceeding rpm_limit. |
provider_error | 502 | The upstream provider failed or is unreachable. | Provider 5xx/timeout while proxying. |
secrets_unavailable | 503 | A required dependency is not available to serve the request. | Secrets key missing (credentials cannot be sealed), webhook secret not provisioned. |
csrf_invalid | 403 | The CSRF proof was missing or did not match the session. | A cookie-authenticated mutating request without a matching X-CSRF-Token. Distinct from forbidden, which means "authenticated but not allowed". |
internal_error | 500 | Unexpected server-side failure. | Unhandled error; check request_id in logs. |
HTTP status mapping
Multiple codes can share a status class. The canonical mapping is:
| HTTP status | Response component | Codes |
|---|---|---|
| 400 | BadRequest | invalid_request, validation_error |
| 401 | Unauthorized | unauthorized |
| 402 | PaymentRequired | budget_exceeded |
| 403 | Forbidden | forbidden, csrf_invalid |
| 404 | NotFound | not_found |
| 409 | Conflict | conflict |
| 429 | RateLimited | rate_limit_exceeded |
| 500 | — | internal_error |
| 502 | — | provider_error |
| 503 | ServiceUnavailable | secrets_unavailable, internal_error (dependency not ready) |
400 responses are declared on every operation; other statuses appear only where they can occur (see each path in openapi.yaml).
Stability
Error code values are part of the stable surface: existing codes are never renamed or repurposed, and new codes may be added in a minor/patch release. Consumers must tolerate unknown codes. See ../API_STABILITY.md.