Errors And Limits
When the Optima API cannot complete a request, it will return an HTTP status code and a body that says what went wrong. This page lists the status codes and error codes you may see, and the limits that apply to each request.
Status Codes
| Code | Meaning |
|---|---|
| 400 | Bad request — malformed JSON, a missing field, or a request the model cannot take (see the error codes below) |
| 401 | Not authenticated — missing, invalid, revoked or expired credentials, or a key used from an address it is not allowed from. The body is empty |
| 403 | Authenticated, but not allowed — the key lacks a scope, or the user must change their password |
| 404 | Not found — no such model, Assistant or stored response, or not one available to you |
| 429 | Too many requests — the key's rate limit was reached |
| 500 | Internal error |
| 503 | Service unavailable — no running model can answer, or the Gateway is not ready |
Error Bodies
Errors from the OpenAI-compatible endpoints use OpenAI's shape. For example:
{
"error": {
"message": "Model 'Qwen3.5-9B' does not accept image input.",
"type": "invalid_request_error",
"param": "messages",
"code": "unsupported_media"
}
}
Authorisation and rate-limit errors use the standard problem details shape — see Authentication and Rate limits below. A request that cannot be read at all, such as malformed JSON, will also return problem details.
Error Codes
| Code | Status | Meaning | What to do |
|---|---|---|---|
context_length_exceeded |
400 | The request does not fit the model's context window | Send less. See Chat Completions |
unsupported_media |
400 | An image was sent as a link, or to a model that does not read images | Send images inline as data: URIs, to a model that reads them |
unsupported_content_type, unsupported_input_item, unsupported_tool_type |
400 | /v1/responses was sent something it does not read — a non-text part, an unknown input item, or a hosted tool |
See Responses |
system_prompt_not_allowed |
400 | The Assistant refuses requests that bring their own system prompt | Leave out the system message |
model_not_found |
404 | No such model or Assistant available to you | Check Listing Models |
previous_response_not_found |
404 | The previous_response_id does not exist, or is not yours |
Start a new conversation |
model_not_available |
503 | The Assistant's models are not running | Try again later, or tell your administrator |
password_change_required |
403 | The user signed in with a temporary password | Change the password. See Authentication |
Errors During Streaming
If something goes wrong after a streamed response has started, an error object will be sent as a final data: event, followed by data: [DONE]:
data: {"error":{"message":"…","type":"service_unavailable","code":null}}
data: [DONE]
Rate Limits
An administrator can limit how many requests an API Key may make per second, minute or hour — for every endpoint, or for particular scopes. Requests made by people signed in to Optima's own apps are not limited.
Responses to a limited key carry these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Requests allowed per window |
X-RateLimit-Remaining |
Requests left in the current window |
X-RateLimit-Window |
second, minute or hour |
When the limit is reached, the request will be refused with 429 and a Retry-After header giving the number of seconds to wait:
{
"title": "Too many requests",
"status": 429,
"detail": "This key is limited to 60 request(s) per minute for chat.completions. Retry in 12s.",
"scope": "chat.completions",
"limit": 60,
"window": "minute",
"retry_after": 12
}
Wait for Retry-After seconds before trying again.
Other Limits
The following limits also apply:
| Limit | Where | See |
|---|---|---|
| The model's context window | Every request | Listing Models — ctx_max |
| Rounds of tool calls | Requests where the Gateway runs tools | Set by your administrator |
| Images | Inline data: URIs only |
Chat Completions |