API reference
Errors
The OpenAI error envelope, every Cairva product code, its HTTP status and what to do about it.
Gateway errors use the OpenAI error envelope, so OpenAI SDKs raise them as normal API errors. Branch on code: it's a stable Cairva product code. The message is for people and can change.
{
"error": {
"message": "allocation_exhausted: 120 input and 0 output tokens remain",
"type": "invalid_request_error",
"code": "allocation_exhausted"
}
}type follows the status: authentication_error for 401, rate_limit_error for 429, api_error for 5xx, and invalid_request_error for everything else.
Codes
| Status | Code | When it happens | What to do |
|---|---|---|---|
| 400 | validation_failed | The body isn't JSON, or a field fails validation. The message names the field | Fix the request. See Chat completions |
| 401 | unauthenticated | The key is missing, malformed, unknown or revoked | Check the key. See Authentication |
| 402 | allocation_exhausted | Not enough input or output allowance remains to admit this request. The message says what's left | Shorten the prompt, wait for running requests to settle, or buy more capacity |
| 402 | allocation_depleted | The allocation used its full allowance and closed | Buy more capacity |
| 403 | scope_missing | The key doesn't have the scope this endpoint needs | Use a key with inference or usage:read |
| 403 | key_unscoped | The key isn't bound to an allocation | Create a key for an allocation |
| 403 | model_not_permitted | model isn't the one model this key's allocation covers. The message names it | Use the id from GET /v1/models |
| 403 | allocation_reserved | The agreement behind the allocation hasn't activated yet | Wait for activation |
| 403 | allocation_not_started | The window hasn't opened. The message includes the start time | Retry after the start time |
| 403 | allocation_expired | The delivery window has ended | Buy new capacity |
| 403 | allocation_paused | The supplier or operations paused the allocation. The message carries the reason when one was given | Read the reason in the workspace |
| 403 | allocation_terminated | The allocation was terminated and won't serve more requests | Buy new capacity |
| 429 | rate_limited | A requests-per-minute, tokens-per-minute or concurrency limit was hit | Wait for Retry-After seconds. See Rate limits |
| 502 | upstream_error | The provider didn't complete the request. The hold is released and nothing is charged | Retry with backoff |
| 502 | route_disabled | Operations paused the route behind this allocation | Check the status page |
| 502 | route_unconfigured | The route has no provider credentials configured | Contact Cairva |
| 500 | internal_error | Something failed inside Cairva | Retry with backoff. Quote the request id if it persists |
Retry-After
Every 429 carries a Retry-After header in seconds: 60 for the requests-per-minute and tokens-per-minute limits, 2 for the concurrency limit. The OpenAI SDKs read it when they retry.
Retrying safely
A request that failed never consumes allowance. Its hold is released when Cairva records the failure. Retrying a 502 upstream_error or a 429 can't double-charge you.
4xx codes other than 429 won't succeed on retry without a change: a new key, a different model, or a new allocation.
Errors inside a stream
A failure after a stream has opened arrives as one event, {"error": {"code": "upstream_error", "message": "..."}}, and then the stream closes. See Streaming.