Errors
The OpenAI-compatible error envelope and status mapping.
Error envelope
Failures are returned as the standard OpenAI error object — never a bare string —
so the openai SDKs parse them directly:
{
"error": {
"message": "No model found with id 'foo/bar'.",
"type": "not_found_error",
"param": null,
"code": "model_not_found"
}
}Error types
type is one of a closed set:
invalid_request_error, authentication_error, permission_error,
not_found_error, rate_limit_error, api_error, overloaded_error.
Status mapping
| Status | When | type |
|---|---|---|
400 | Request failed validation, or an unsupported param (e.g. n > 1) | invalid_request_error |
401 | Missing or invalid API key | authentication_error |
402 | Insufficient balance or billing not configured | invalid_request_error |
403 | API key has no organization | permission_error |
404 | Unknown model, or a response id not found / not owned | not_found_error |
429 | Rate limit exceeded, or upstream rate limit | rate_limit_error |
502 | Upstream provider error, or a missing provider key | api_error |
503 | A required dependency was unavailable (fail-closed) | api_error |
500 | Unhandled error | api_error |
Where applicable the body includes a more specific code (e.g.
model_not_found, provider_key_missing, background_unavailable) and a param
pointing at the offending field.
Streaming errors
Once a stream has started, the HTTP status is already 200. A later failure is
delivered in-band as a terminal error frame (event: error for responses, a
data: error object for chat) followed by the stream's end marker, rather than
changing the status code.