GET /v1/models and POST /v1/chat/completions uses the same JSON envelope. An error inside a stream uses it too, with param: null — see Streaming. Branch on error.code, never on error.message.
A path the API does not serve returns a bare status with an empty body, before the key is checked: 404 for an unknown path under /v1 (for example /v1/embeddings or /v1/models/{id}), and 405 for a method the path does not accept. Check the status before you parse the body.
The error envelope
The broad class:
invalid_request_error, insufficient_quota, permission_error, rate_limit_error or server_error.The request field the error refers to, written as OpenAI writes it, for example
messages[0].content. null when no single field is at fault, such as a body that is not JSON.The same value as the
x-request-id header, which every response carries. Include it in a support request.Codes
GET /v1/models returns only 401, 403 and 503 codes from this table.
After a stream has started, a failure arrives as the last event: upstream_timeout for a timeout, upstream_error for anything else — see Streaming.
What to do about each code is in Common problems.
Retries
A code marked Yes always comes with aRetry-After header, in seconds. Wait at least that long, then send the request again. rate_limit_exceeded can ask for up to 3,600 seconds; the others ask for 60 seconds or less. A refused request is not queued: nothing runs unless you send it again.
A code marked No is not cleared by retrying. Change the request, the account or the limit first — see Common problems.
502 and 504 happen after the request started, so part of it may have run and be charged — see What is billed. A retry is a new request and is charged separately.
Every other error is returned before generation starts and is not charged.
There is no idempotency key, and a response that broke off is not resumed.