Errors use the OpenAI envelope, so openai.APIError and its subclasses work unchanged:

Status codes

The ones that are specific to this API

The quote for this request exceeds your Circle Gateway balance. Retrying will not help.Before you top up, check 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.
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.
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.
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.
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 for 503 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

A 404 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

Never retry a 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.