Errors
OpenAI-compatible error envelope, status codes, and types returned by the OpenToken API.
OpenToken returns errors in the OpenAI-compatible envelope. Every failed request carries a JSON body with a single error object.
{
"error": {
"message": "model \"openai/gpt-4o\" not found",
"type": "invalid_request_error",
"code": "model_not_found"
}
}message— human-readable description of what went wrong.type— broad category, aligned with the HTTP status.code— specific machine-readable reason. May benullwhen no finer code applies.
Status codes
| HTTP | type | code | When |
|---|---|---|---|
| 400 | invalid_request_error | model_not_found | The {provider}/{model} id is not registered. See Models. |
| 400 | invalid_request_error | — | Malformed body, unknown field, or failed schema validation. |
| 401 | authentication_error | — | Missing or invalid Authorization header. Keys start with sk-optk-. |
| 402 | invalid_request_error | insufficient_credit | The workspace credit balance is non-positive or no billing account exists. |
| 404 | invalid_request_error | not_found | The request path does not match a known route. |
| 429 | invalid_request_error | spend_limit_exceeded | A per-key spend limit was reached. |
| 500 | api_error | — | Unexpected internal error. Carries an extra event_id field for support correlation. |
| 502 | upstream_error | vertex_auth_failed | Upstream credential exchange failed (Vertex). |
| 503 | upstream_error | no_supplier | No provider is available to serve the model. |
| 504 | upstream_error | upstream_timeout | The upstream provider did not respond in time. |
An unregistered id such as openai/gpt-4o returns 400 model_not_found (no openai/* model is in the catalog). The full set of routable model ids is on the Models page.
Errors during streaming
When stream: true, a request can succeed with 200 OK and then fail mid-stream. In that case the error is delivered as a plain data: line carrying the error envelope rather than an HTTP status. The stream still terminates with a data: [DONE] line afterward.
data: {"error":{"message":"stream interrupted","type":"upstream_error","code":"stream_error"}}
data: [DONE]Parse each data: line for an error key in addition to checking the initial HTTP status. See Streaming.
Handling errors
Branch on error.code when present and fall back to error.type otherwise. Treat 429, 503, and 504 as retryable; treat 400, 401, and 402 as terminal until the request or account state changes.