Skip to content

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