Skip to main content

Errors and rate limits

Error object​

Every error response has the OpenAI error shape, so SDK exception classes map directly.

{
"error": {
"message": "Rate limit reached. Please retry after 12 seconds.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
}
FieldMeaning
messageHuman-readable description. Safe to log; do not show it to end users verbatim.
typeCategory: invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error or server_error.
codeMachine-readable code: invalid_request_error, invalid_api_key, permission_denied, model_not_found, not_found, context_length_exceeded, too_many_images, request_too_large, rate_limit_exceeded, upstream_unavailable, upstream_error or timeout. May be null.
paramThe request parameter the error refers to, when applicable. May be null.

HTTP status codes​

StatustypeWhenWhat to do
400invalid_request_errorMalformed JSON, unknown or out-of-range parameter, or prompt larger than the context window (context_length_exceeded).Fix the request. Do not retry as is.
400invalid_request_errorMore images than the model reads, counted over the whole conversation: from 1 to 8 depending on the model (see Image input), for example This model reads at most 1 image(s) per request. on paddleocr-vl-1.6. code is too_many_images and param is messages (input on POST /v1/responses). The limit of each model is supported_inputs.references.max of its image input modality in GET /v1/models.Send only the most recent images, up to the limit, and replace the older ones with a short text. Do not retry as is.
400invalid_request_errorTwo function tools with the same name in tools (More than one tool is named 'get_weather': each tool needs its own name.). param points at the second one: tools[1].function.name on POST /v1/chat/completions, tools[1].name on POST /v1/responses. Names are compared exactly, letter case included. See Tool calling.Give each tool its own name. Do not retry as is.
400invalid_request_errorOn embeddings, rerank and redaction: a model sent to a route that does not serve it (The model 'qwen3-reranker-0.6b' is not served on /v1/embeddings., param: "model"), or a request the model could not process as sent (The model server rejected the request. Check the input sizes and parameters.).Use the model of the route, or shorten the inputs and check the parameters. Do not retry as is.
401authentication_errorMissing, malformed or revoked API key.Check the Authorization header and the key.
403permission_errorThe key is valid but not allowed to use this model or feature, for example because of its plan or credit balance (This API key is not allowed to use this model or feature. Check your account, plan or credits.), or because it cannot use the decision endpoints yet, as with keys from a Serenity Star account (permission_denied). The embeddings, rerank and redaction routes name their API in the message: This API key cannot use the embeddings API. Use a Serenity Edge API key. (rerank, redact).Check your plan, credits or contract; for decisions, embeddings, rerank and redaction, use a Serenity Edge API key. Do not retry as is.
404not_found_error or invalid_request_errorUnknown model id or path.Check GET /v1/models.
413invalid_request_errorRequest body larger than 4 MB, than 192 KiB (196,608 bytes) on POST /v1/redact, or than 16 MiB on POST /v1/audio/transcriptions (request_too_large).Reduce the request. Do not retry as is.
422invalid_request_errorPOST /v1/systemone only: the decision model refused a question or the state, as Jev's format does. The same refusal is a 400 on POST /v1/decisions. See Decisions.Fix the request. Do not retry as is.
429rate_limit_errorToo many requests per minute or in flight for your access route or key, or the model temporarily at capacity (rate_limit_exceeded). See Rate limits and HTTP 429.Wait for Retry-After, then retry with backoff.
500server_errorThe model service returned an unexpected response (upstream_error), the request took longer than 600 seconds (timeout), a file took too long to transcribe on POST /v1/audio/transcriptions (timeout), or an unexpected error in the gateway.Retry with backoff; for timeout, reduce max_tokens, or split the audio into shorter requests.
503server_errorThe model service is temporarily unavailable (upstream_unavailable).Retry later; check the status page.

A 500 or 503 that persists across retries usually means an incident or a capacity event rather than a problem with your request. The current and historical availability of the API is published on the status page at status.serenityedge.ai; check it before opening a support request. Its monitors send real requests through the public API with a Serenity Edge API key of our own: a health check of the API every minute, and every five minutes a request to each chat model, the document OCR model and each decision model, a streamed request and an embeddings request, which stands for the routing layer shared by embeddings, rerank and redaction. They do not use the Serenity Star route or a router or marketplace, and Sandboxes are not on the status page yet.

Rate limits and HTTP 429​

Rate limits count requests, not tokens: there is no tokens-per-minute limit. A request can be refused with HTTP 429 for two reasons:

  • The limits of your access route. A router or marketplace or an enterprise contract can have a limit of requests per minute and a limit of requests in flight (sent and not yet answered), shared by every key of that route; a key can also have limits of its own. They are set per route or contract.
  • The capacity of the model. Each model serves a limited number of requests at a time. The access routes share that capacity, a router or marketplace up to its own share of it, and no single route can take all of it, so that one route's peak does not take a model from the others. When the model, or your route's share of it, is full, the request is refused at once rather than queued.

Either way the API returns HTTP 429 with:

  • a Retry-After header with the number of seconds to wait;
  • an error of type rate_limit_error and code: "rate_limit_exceeded".

There is no separate code for an exhausted credit balance. On a key from a Serenity Star account, a request that the account's plan or credit balance does not cover is refused with HTTP 403 and code: "permission_denied" (see the table above). Top up in your Serenity Star account rather than retrying.

Handling 429 correctly​

  1. Read Retry-After and wait at least that long.
  2. Retry with exponential backoff and jitter; cap the number of attempts.
  3. Do not spin up more concurrency in response to 429. The limits count requests per minute and requests in flight for your route, so extra workers make it worse.
  4. Send through a fixed number of workers rather than in bursts: a burst over the in-flight limit is refused at once, however short its requests are.

The official OpenAI SDKs retry 429, 500 and 503 automatically with backoff. Set max_retries to tune this:

from openai import OpenAI

client = OpenAI(
base_url="https://api.serenityedge.ai/v1",
api_key="YOUR_SERENITY_EDGE_API_KEY",
max_retries=5,
)

Raising your limits​

Limits scale with your access route. A router or marketplace applies its own account limits. A Serenity Star account starts with a default allowance that grows with usage. An enterprise contract sets limits and reserved capacity explicitly. If a default limit blocks you, write to contact@substrate.ai with your key prefix and the throughput you need.

Timeouts​

Long generations can take a while. Set the client timeout to at least 60 seconds for non-streaming requests, or use streaming so the connection stays active while tokens arrive.