Error Handling
How OffRail returns errors in an OpenAI-compatible format on the OpenAI-compatible endpoints.
Error Handling
On the OpenAI-compatible endpoints, OffRail returns errors in the same format as the OpenAI API, so existing OpenAI SDKs and tooling can parse gateway errors without changes. This applies to errors forwarded from upstream providers as well as errors raised by the gateway itself (authentication failures, usage limits, validation problems, timeouts, and so on).
Error Format
Errors on the OpenAI-compatible endpoints (/v1/chat/completions, /v1/embeddings, /v1/images, /v1/models, /v1/moderations, /v1/rerank, /v1/responses, /v1/videos) use the standard OpenAI error envelope:
{
"error": {
"message": "Unauthorized: OffRail API key reached its usage limit.",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}| Field | Description |
|---|---|
error.message | Human-readable description of what went wrong. |
error.type | High-level error category (see the table below). |
error.param | The request parameter that caused the error, or null when not parameter-specific. |
error.code | A more specific machine-readable code, or null when no specific code applies. |
The HTTP status code on the response always matches the error and is the authoritative signal — read it from the response status line rather than the body.
Status Codes
The gateway maps HTTP status codes to OpenAI error types and codes as follows:
| Status | type | code |
|---|---|---|
| 400 | invalid_request_error | (varies / null) |
| 401 | invalid_request_error | invalid_api_key |
| 402 | invalid_request_error | billing_error |
| 403 | invalid_request_error | permission_denied |
| 404 | invalid_request_error | not_found |
| 408 | timeout_error | timeout |
| 413 | invalid_request_error | request_too_large |
| 415 | invalid_request_error | unsupported_media_type |
| 429 | rate_limit_error | rate_limit_exceeded |
| 499 | invalid_request_error | request_cancelled |
| 504 | timeout_error | timeout |
| 5xx | api_error | (null) |
Validation errors raised before a request reaches a provider often include a
more specific code and a param pointing at the offending field — for
example invalid_json, model_not_found, or
unsupported_parameter_combination.
Streaming Errors
For streaming requests ("stream": true), an error that occurs after the stream has started is delivered as an SSE error event whose payload uses the same { "error": { ... } } envelope. Errors that occur before streaming begins (such as authentication failures) are returned as a normal JSON error response with the appropriate status code.
Related
- Request Timeouts for
504handling. - Routing for eligible retry and fallback behavior.