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"
  }
}

Field	Meaning
message	Human-readable description. Safe to log; do not show it to end users verbatim.
type	Category: invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error or server_error.
code	Machine-readable code such as invalid_api_key, model_not_found, context_length_exceeded or rate_limit_exceeded. May be null.
param	The request parameter the error refers to, when applicable. May be null.

HTTP status codes

Status	type	When	What to do
400	invalid_request_error	Malformed JSON, unknown or out-of-range parameter, prompt larger than the context window.	Fix the request. Do not retry as is.
401	authentication_error	Missing, malformed or revoked API key.	Check the Authorization header and the key.
403	permission_error	The key is valid but not allowed to use this model or feature.	Check your plan or contract.
404	not_found_error or invalid_request_error	Unknown model id or path.	Check GET /v1/models.
429	rate_limit_error	Requests or tokens per minute exceeded, or credits exhausted.	Wait for Retry-After, then retry with backoff.
500	server_error	Unexpected error.	Retry with backoff.
503	server_error	Temporarily at capacity.	Wait for Retry-After, then retry with backoff.

Rate limits and HTTP 429

Each API key has a requests-per-minute and a tokens-per-minute allowance. Exceeding either returns HTTP 429 with:

• a Retry-After header with the number of seconds to wait;
• an error of type rate_limit_error.

A 429 with code: "insufficient_credits" means a prepaid balance has run out; 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. Rate limits are per key, so extra workers make it worse.
4. Reduce the number of prompt tokens when you hit the token limit: shorter system prompts, fewer conversation turns, and cached input for repeated prefixes.

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. OpenRouter 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 [email protected] 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.