Errors

Errors use the error shape of the endpoint you called.

OpenAI endpoints

{ "error": { "message": "Insufficient balance", "type": "insufficient_quota", "code": "insufficient_balance" } }

Messages

{ "type": "error", "error": { "type": "billing_error", "message": "Insufficient balance" } }

Status	Code	Meaning	Retry?
400	invalid_request	Malformed body, missing model, bad output limit	No
400	model_not_found	Unknown model ID	No
400	unsupported_content	Non-text content (images, audio, files)	No
400	unsupported_tool	Tool type other than function	No
400	unsupported_parameter	n > 1, best_of, previous_response_id, thinking, store: true	No
401	invalid_api_key	Missing, revoked or unknown key	No
402	insufficient_balance	Balance cannot cover the request	After topping up
402	key_limit_exceeded	The key’s monthly spend limit is reached	Next month, or raise the limit
403	account_suspended	Account suspended	No; contact support
403	content_policy_violation	The request was refused by the content policy	No
429	rate_limited	Over requests per minute	Yes, after retry-after
429	concurrency_limited	Too many requests in flight	Yes, after retry-after
429	plan_limit_reached	The plan’s session or weekly limit is used up and the balance cannot cover the request; resets_at says when it resets	After resets_at, or after topping up
502	upstream_error, upstream_unavailable	Model backend failed	Yes, with backoff
503	server_busy	Service at capacity	Yes, after retry-after
503	billing_unavailable, shutting_down, content_policy_unavailable	Transient	Yes
504	upstream_timeout	Generation exceeded 9 minutes	No: this request was charged

503 responses carry x-should-retry: true; 504 carries x-should-retry: false so SDKs do not retry and charge you twice.

If an error happens after a stream has started, the stream ends early without a final usage event.