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.
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 will fail again until something changes on your side.
Timeouts: replies wait up to ~60 seconds before the endpoint reports a timeout error. If your client times out first, the turn may still complete server-side and accrue cost — prefer a client timeout at or above 60s, or use streaming so progress is visible.
OpenAI SDK retry policies work unchanged: the codes and headers match what they expect.