Errors
Error statuses and shapes, which ones to retry, and how long a request can take.
Error shape
Gateway-generated errors follow each API's own format. Chat Completions, Responses and GET /v1/models return:
{
"error": {
"message": "Incorrect API key provided.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}For errors generated by the gateway, Messages returns the Anthropic format, which has type but no code:
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "Incorrect API key provided."
}
}The SDKs turn these into exceptions, such as openai.AuthenticationError and anthropic.RateLimitError.
Model server validation errors can be relayed in a different format. For example, a Messages request can receive an HTTP 400 body with error.type: "upstream_error" and error.code: "upstream_http_error", without a top-level type. An unexpected internal failure can also use an OpenAI-style envelope. Inspect the HTTP status and full error body rather than assuming every Messages error has the shape above.
Status codes
| Status | code | Cause | Retry? |
|---|---|---|---|
| 400 | invalid_request | The body is not valid JSON, misses a required field, or uses a refused feature. | No. Fix the request. |
| 400 | unsupported_tool | A tool Raon does not run, such as code_interpreter. | No |
| 400 | token_limit_exceeded | One request exceeds a per-minute token limit. | No |
| 400 | — | The input and max_tokens together exceed the context window. | No. Shorten the input. |
| 401 | invalid_api_key | The key is missing, wrong, disabled or expired. | No |
| 402 | insufficient_credit, spend_limit_exceeded | No credit left, or the monthly spend limit is reached. | No |
| 403 | model_not_allowed | The model ID is wrong, or your key cannot use that model. | No |
| 404 | — | The path is not served, often a base URL with a missing or doubled /v1. | No |
| 413 | payload_too_large | The body is over 28 MiB. | No |
| 429 | rate_limit_exceeded, overloaded | See Rate limits. | Yes, after retry-after |
| 500 | — | An error inside Raon. | Yes, with backoff |
| 502 | upstream_error | The model server failed or did not answer in time. | Yes, with backoff |
Retry with growing waits, and stop after a few attempts. Do not retry 4xx errors other than 429; the same request fails the same way.
The model price is zero during this preview. A 402 still indicates an organization policy check; contact the preview operator rather than looking for a payment or spend-settings page.
Errors during a stream
A streamed response has already sent 200 when it starts, so an error after that arrives as an event in the stream:
| API | Error event |
|---|---|
| Chat Completions | a data: line holding {"error": {...}} |
| Responses | event: error |
| Messages | event: error, in the Anthropic format |
The SDKs raise these as exceptions while you iterate. Text received before the error is incomplete; send the request again if you need the whole answer.
Timeouts
Reasoning and web search can make an answer take minutes. Raon gives a request up to 10 minutes; set your client's timeout to at least that. The OpenAI and Anthropic SDKs wait 10 minutes by default.
- Streaming shows progress sooner and keeps the connection busy. When the model is silent for 10 seconds, for example during a web search, Raon sends a
: pingcomment line, which SSE clients skip. - If your client disconnects, Raon stops the request.
- Requests must state their size in
Content-Length. The SDKs and curl do; a chunked upload without it returns 411.
Reporting a problem
Include the request time, the response's x-request-id header, status code, and error body. Raon generates this tracking UUID for each request, including streamed responses. A client-supplied x-request-id does not override it.