Error Handling
Text, OCR and STT errors follow the OpenAI error format. RelayOn returns its own messages and keeps provider details in operator Diagnostics. Invalid API keys are rejected before model and capacity checks.
{
"error": {
"message": "Model not found",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
| 400 | — | — | Invalid request (missing params, bad JSON) |
| 400 | invalid_response_format / invalid_temperature | — | Malformed JSON format option or temperature outside 0–2; rejected before inference |
| 401 | — | — | Authentication required |
| 403 | — | — | Provider/model not allowed for this key |
| 403 | account_suspended | — | The API key owner is suspended. Contact support; requests are not served or billed. |
| 404 | — | — | Model not found |
| 402 | insufficient_credits / budget_exceeded / model_not_priced | — | Insufficient balance, a spending cap, or an unpriced operated model |
| 422 | encrypted_pdf | OCR | Upload an unencrypted PDF |
| 422 | unsupported_option | Text | The selected model does not support one or more requested options |
| 422 | context_limit_exceeded | Text | Shorten the input or lower max_tokens |
| 422 | unsupported_format / unprocessable_document / too_many_pages | OCR | Use a supported, valid document within the page limit |
| 413 / 422 | document_too_large | OCR | Upload a smaller document |
| 429 | — | — | RelayOn API key request limit exceeded. Honour Retry-After (seconds). |
| 400 | invalid_request_parameters | Text | The model rejected request parameters; check messages and generation options |
| 502 | upstream_connection_error | — | Connection to the generation service failed |
| 503 | upstream_unavailable | — | The generation service is temporarily unavailable |
| 504 | upstream_timeout | — | The generation service did not respond before the deadline |
| 500 | internal_error | — | RelayOn could not complete the request; provider details are masked |
| 500 | no_text_extracted | OCR | No readable text was extracted |
| 503 | no_capacity | — | No account slot is available after bounded waiting and fallbacks; honour Retry-After |
| 503 | state_unavailable | — | Request capacity is temporarily unavailable; honour Retry-After |
Unsupported model options
When a selected model does not support an option, RelayOn returns 422 unsupported_option instead of a generic server error. Adjust the model-specific options before retrying. Unexpected service errors still return 500 internal_error; provider messages and credentials are not exposed.
{
"error": {
"message": "This model does not support one or more requested options.",
"type": "invalid_request_error",
"param": null,
"code": "unsupported_option"
}
}Capacity failures
Temporary account saturation waits briefly for a slot. If none becomes available, the request returns 503 no_capacity. A capacity service failure returns 503 state_unavailable. Both responses include Retry-After in seconds. Retry after that delay; validation errors require changing the request. A stream that has already started is never automatically restarted.
Streaming failures
Chat Completions, Responses and Messages check the initial response before committing the stream. An error detected at that point can return an HTTP error status, including 422 unsupported_option, 503 no_capacity or 500 internal_error.
After a text stream starts, failures arrive as a safe error object in an SSE data: event; the HTTP status can no longer change. The same public error codes are preserved, while unexpected service errors become internal_error. Clients must inspect stream events as well as the initial HTTP status.
JSON repair outcomes
A failed JSON repair is not an inference error: the original completion is returned with its existing status, usage and finish reason. Inspect X-RelayOn-JSON-Repair and parse the content yourself. See Automatic JSON repair for failure and skip reasons.