openai.APIError and its subclasses work
unchanged:
Status codes
The ones that are specific to this API
402 — insufficient funds
402 — insufficient funds
max_tokens. The quote is priced at that number and
held until the request settles — an account with money in it can still refuse
its own second call because the first one’s hold has not cleared. Lowering
max_tokens often fixes a 402 without any deposit at all.Otherwise: fund the account.429 — too much in flight
429 — too much in flight
Not a rate limit. A payer may have at most $1.00 of quoted, unsettled
requests in flight at once, and this request would cross it.It clears on its own as requests settle, so a short backoff works — a second or
two, not a minute. If you hit it constantly, your concurrency is fine and your
max_tokens is too high: the exposure is measured in money, not in requests.403 — limit or wallet
403 — limit or wallet
Two different causes, distinguishable from the message.Key spending limit:Raise the limit on the keys page, or use a
different key.No usable wallet: the account has no wallet the router can sign against.
Sign in to the dashboard once to provision one.
502 — not your fault
502 — not your fault
Something on the router’s side broke rather than something in your request:
signing, facilitator, or nonce failure in the payment machinery, or the upstream
relay failing or ending a turn without ever writing an answer.This is deliberately not a
402. Answering a router fault with “payment
required” would tell you to pay for something you cannot fix. Retry.The message says which. A 502 raised after the model has already worked —
searched, fetched, or generated — is billed for that work; see below.503 — no capacity
503 — no capacity
No upstream account is available to serve the request. Retry with backoff.
A failed request is not billed
If a request fails before producing anything, the whole quote is refunded — zero usage means zero charge. You pay in latency, not in USDC. This matters for503 in particular: a model that is temporarily unavailable
costs you a round trip and nothing else.
“Producing anything” includes work you never see. A turn that searched twice
and then failed is billed for those searches and for the tokens the model had
already generated, because both really happened. The error is free; the work
behind it is not. GET /api/requests/{id} shows exactly what was charged.
Model availability drifts
A404 on a model that worked an hour ago is possible. Availability is not
stable, and the two upstream failure modes mean different things: one is
permanent for an account type, the other comes and goes.
GET /v1/models is narrowed to models that are genuinely buyable right now.
Fetch it at startup rather than hardcoding names, and treat a 404 as a signal
to refresh rather than a permanent verdict.
Suggested retry policy
402 in a loop. It will not succeed, and each attempt is a real
round trip against a balance that is not going to grow on its own.