Errors

Standard shapes, actionable messages.

Errors use the OpenAI error envelope, with HTTP status codes you already know. The message is written to be actionable: it names what to fix.

Error shape

{
  "error": {
    "message": "rate limit exceeded",
    "type": "invalid_request_error",
    "code": 429
  }
}

message: a human-readable explanation of what went wrong and, where possible, what to do about it.
type: the error family. Currently invalid_request_error for all request-level failures and stream_error for mid-stream failures (see Streaming).
code: the HTTP status code, mirrored in the body for convenience.

Status	Meaning	Typical cause / fix
400	Bad Request	Malformed JSON; no user message in `messages`; unknown or unavailable model id; bad `conversation` or `room` value. Fix the request body.
401	Unauthorized	Missing/malformed bearer header, or the key is revoked or expired. Check the header; rotate the key if needed.
402	Payment Required	The key's spend cap is exhausted. Raise the cap on the keys page or switch keys.
403	Forbidden	The public API is disabled for this room. A room owner/admin can enable it in room settings.
405	Method Not Allowed	The endpoint only accepts POST.
413	Request Entity Too Large	The request body exceeds the 200 MiB limit, typically a multimodal payload over the per-turn ceilings (5 images × 6 MiB, 10 documents × 10 MiB, base64-encoded, see Multimodal input). Trim or split the payload and resend; the request is refused before any spend accrues.
429	Too Many Requests	Per-key rate limit exceeded. Read `x-ratelimit-reset-requests`, wait that many seconds, retry once.
500	Internal Server Error	Something failed on our side. Safe to retry with backoff. If it persists, contact support.

Retry with backoff: 429 and 5xx. Honor x-ratelimit-reset-requests on 429 rather than fixed sleeps.
Do not retry blind: 400, 401, 402, 403, 413 will fail again until something changes on your side.
Timeouts: replies wait up to ~3 minutes (180 seconds) before the endpoint reports a timeout error. The wait ceiling is operator-tunable on our side (180s is the default). If your client times out first, the turn may still complete server-side and accrue cost. Prefer a client timeout at or above 180s, or use streaming so progress is visible.
OpenAI SDK retry policies work unchanged: the codes and headers match what they expect.