Errors

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

{
  "error": {
    "message": "insufficient Gateway balance for this request",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Status codes

Status	Retry?	Meaning
`400`	No	Malformed body or unsupported parameter
`401`	No	Missing, unknown, revoked, or expired API key
`402`	No	Your Gateway balance will not cover the quote
`403`	No	Key spending limit exceeded, or no usable wallet
`404`	No	Unknown model
`429`	Yes	Too much of your money in flight, unsettled
`500`	Maybe	Internal router error
`502`	Yes	The router’s own payment machinery failed
`503`	Yes	No upstream capacity

The ones that are specific to this API

402 — insufficient funds

{ "error": { "message": "insufficient Gateway balance for this request" } }

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.

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

Two different causes, distinguishable from the message.Key spending limit:

this API key has 0.412000 USDC left under its spending limit;
this request quotes 0.640000 USDC

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

Signing, facilitator, or nonce failure — the router’s own payment machinery breaking, not a problem with your request or your balance.This is deliberately not a 402. Answering a router fault with “payment required” would tell you to pay for something you cannot fix. Retry.

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 for 503 in particular: a model that is temporarily unavailable costs you a round trip and nothing else.

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

from openai import OpenAI, APIStatusError
import time

def complete(client, **kwargs):
    for attempt in range(4):
        try:
            return client.chat.completions.create(**kwargs)
        except APIStatusError as e:
            if e.status_code in (429, 502, 503):
                time.sleep(2 ** attempt * 0.5)
                continue
            raise          # 400/401/402/403/404 will not improve
    raise RuntimeError("exhausted retries")

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.

Inference

Reference

Status codes

The ones that are specific to this API

A failed request is not billed

Model availability drifts

Suggested retry policy

​Status codes

​The ones that are specific to this API

​A failed request is not billed

​Model availability drifts

​Suggested retry policy

Status codes

The ones that are specific to this API

A failed request is not billed

Model availability drifts

Suggested retry policy