Errors & Retries

How Errors Arrive

Codex is a GraphQL API, so most errors come back in the errors array of an otherwise normal response — HTTP 200 with an errors key, not an HTTP error status. Authentication, payment (402), malformed queries (400), rate limiting and infrastructure failures (502, 503, 504, and an HTML 403 from the edge firewall) fail at the HTTP layer instead; see the table below.

{
  "errors": [
    {
      "message": "The requested resources are over capacity. Retry in about 30 seconds — retrying sooner will be throttled.",
      "extensions": {
        "code": "OVER_CAPACITY",
        "retryAfterSeconds": 30
      }
    }
  ]
}

If your error handling only inspects HTTP status codes, it will treat these as successful responses. Always check whether the body contains an errors array.

Which Errors to Retry

There is one field to watch: if an error carries extensions.retryAfterSeconds, wait that many seconds before retrying that request. On rate-limited responses the same value is also sent as the standard Retry-After header, so most HTTP client libraries will honor it without any code from you.

Code	HTTP status	Meaning	Retry
`TOO_MANY_REQUESTS`	429	You exceeded your plan’s rate limit	After `retryAfterSeconds`, or your own backoff if absent
`OVER_CAPACITY`	200	We’re briefly over capacity and scaling up	After `retryAfterSeconds`
`UNAUTHENTICATED`	401	Unknown or invalid API key	No, fix the API key
(none)	402	No `Authorization` header: the request is treated as a pay-per-query MPP call and returns `application/problem+json`	No, send your API key
`FORBIDDEN`	403	Your key is valid but the account or key is not allowed to make this request — see Forbidden (403)	No — fix the account state first
(none, HTML page)	403 `Request blocked`	The edge firewall blocked the client IP before the request reached the API (unlike the JSON `FORBIDDEN` 403)	Back off; send the CloudFront request ID and your egress IP to support
`ROUTER_UNAVAILABLE`	503	Brief server-side outage	Yes, after `Retry-After` (2 seconds)
(none)	502, 504	The load balancer could not reach the API; the response has no GraphQL body	Yes, with backoff; include the request ID if it repeats
`NOT_FOUND`	200	What you asked for isn’t indexed, such as `tokenWalletStats` for a token we don’t track	No — see Request errors
`INVALID_ARGUMENT`	200	An argument is malformed or unsupported: an unknown `networkId`, a malformed address or ID	No, fix the argument
`BAD_USER_INPUT`	200, or 400 for a variable	An argument failed validation	No, fix the input
`NOT_AUTHORIZED`	200	Your plan doesn’t include this field: `Not authorized: please upgrade your plan`	No, upgrade your plan
`GRAPHQL_VALIDATION_FAILED`	400	The query doesn’t match the schema, such as a field that doesn’t exist	No, fix the query
Everything else	200	Unexpected failure on our side	Not automatically — see below

Rate limited

A TOO_MANY_REQUESTS error means you exceeded your plan’s per-second rate limit. When we can tell you exactly when the limit lifts, we do, via retryAfterSeconds and the Retry-After header. A 429 without retryAfterSeconds means your request budget is momentarily empty rather than your account being throttled — capacity typically returns within a second. Back off on your own schedule and retry; don’t retry immediately in a tight loop. See Rate Limits & Connection Limits for the limits themselves.

Over capacity

An OVER_CAPACITY error means the data your query needs is temporarily under more load than it can serve, and we’re scaling up. It is not caused by anything wrong with your request — the same query will succeed once you retry. These arrive as HTTP 200 with the error in the body. Retry after retryAfterSeconds (currently 30). Retrying sooner is likely to be throttled and slows the recovery for everyone.

Request errors

NOT_FOUND, INVALID_ARGUMENT, BAD_USER_INPUT, NOT_AUTHORIZED and GRAPHQL_VALIDATION_FAILED mean the request can’t succeed as written, so retrying won’t help. Branch on extensions.code rather than the message text: messages are written for people and can change. One exception has no code. An input value written inline in the query that doesn’t match its type, such as a missing required field, returns HTTP 200 with only a message. Pass inputs as variables and the same mistake returns 400 BAD_USER_INPUT.

Forbidden (403)

A FORBIDDEN error means the API key was recognized but the request is not allowed right now. The message says why:

Message	Meaning	What to do
`Your account has exceeded its usage limit for this billing period, please upgrade your plan`	The account has used its whole allowance for the period and is paused until the period rolls over.	Upgrade your plan, or wait for the next period.
`Your API key is not activated.`	The key has been deactivated.	Reactivate it or create a new one in the dashboard.
`You've exceeded the maximum number of connections, please upgrade your plan`	The key has reached its WebSocket connection limit.	Close connections you no longer need, or upgrade. See Rate Limits & Connection Limits.
`Websockets are not enabled for your account, please upgrade your plan`	Your plan does not include subscriptions, or WebSockets are not enabled on this API key.	Upgrade, or contact support if your plan includes them.
`Your account has violated terms of service, please contact support`	The account has been suspended.	Contact support.

Over WebSocket, the same conditions close the connection with code 4403 and the message as the close reason. An account that becomes paused while a subscription is running is disconnected within about a minute with the reason Forbidden. On compute-unit plans (see Compute Units), two more 403 messages can appear:

Message	Meaning	What to do
`Your account has an unpaid invoice, please update your payment method`	An invoice could not be collected and every key on the account is paused.	Pay the invoice from the billing portal (Pay invoice on the billing page). Access is restored by the payment; a new billing period does not lift the pause.
`This API key has reached its configured compute-unit limit.`	This key has its own custom compute-unit limit and has used all of it. Other keys on the account are unaffected.	Raise or remove the key’s limit in the dashboard, or wait for the period to roll over.

With auto-scale off, using the whole allowance pauses every key on the account and returns Your account has exceeded its usage limit for this billing period, please upgrade your plan until the period rolls over. Turn auto-scale on to keep requests working past the allowance.

Everything else

Unexpected errors return a generic message with an error code:

{
  "errors": [
    {
      "message": "Something went wrong. Error Code: 1a2b3c4d5e6f7890"
    }
  ]
}

Don’t retry these automatically — the same request will usually fail the same way. Include that error code when you contact support or ask on Discord; it lets us find the exact failure in our logs.

Retry Strategy

Fixed retry intervals are the most common cause of prolonged rate limiting. If your interval is shorter than the penalty window, every retry lands inside it and extends the problem.

A retry policy that works well against Codex:

Honor retryAfterSeconds whenever it’s present. It’s computed from the actual condition — it isn’t a guess, and it overrides whatever interval you’d otherwise use.
Otherwise use exponential backoff with jitter. Jitter matters if you run multiple workers: without it they synchronize and retry in a thundering herd.
Cap your retries. Three to five attempts is plenty; past that the condition needs attention rather than another request.
Don’t retry non-retriable errors. Auth failures and malformed queries will fail identically every time.

If you’re hitting rate limits often enough that retry behavior matters, Optimization covers how to reduce request volume — usually the better fix.

First steps

Codex for Agents

Concepts

Recipes

Migration Guides

Resources

Errors & Retries

How Errors Arrive

Which Errors to Retry

Rate limited

Over capacity

Request errors

Forbidden (403)

Everything else

Retry Strategy

​How Errors Arrive

​Which Errors to Retry

​Rate limited

​Over capacity

​Request errors

​Forbidden (403)

​Everything else

​Retry Strategy

How Errors Arrive

Which Errors to Retry

Rate limited

Over capacity

Request errors

Forbidden (403)

Everything else

Retry Strategy