Open-model errors

Should I retry?

The absence of the retry headers is a deliberate signal, not an oversight. A JSON 400, 401, 402, 403, 404 or 413 needs a different request or different credentials, so none carries timing. An HTML 403 needs a pause before retrying.

Key creation and rotation errors (api_key_rotation_overlap_limit, api_key_mint_busy) are on Rotate, revoke, expire.

Status and code reference

The 503 codes

A 503 means the gateway could not safely serve the request. During a rate-limit store outage, each server applies rate limits on its own instead of returning limiter_unavailable, but hosted admission and Idempotency-Key checks can still return a retryable 503. All of them carry Retry-After except upstream_http_error, which forwards one only when the model supplied it, and hosted_inference_unavailable, which carries none. For datastore_unavailable, hosted_evidence_unavailable, hosted_admission_unavailable and the connection gate's limiter_unavailable, the wait is randomized between 1 and 4 seconds, up to 8 under heavy load.

Retired plan limit recovery

Coding plans are retired for new customers. For existing holders of the open-models service, a serving coding plan returns 402 plan_limit_reached when a plan window is at its limit and neither credits nor Standby can serve the request. The response carries x-should-retry: false and no Retry-After. It is a billing refusal; temporary Standby capacity refusals use 429 with retry timing.

The fields sit directly inside error, not under details. Read the blocking window, its exact counters, and the next step from your response.

credits.blocker is disabled, balance_negative, key_limit, empty, cap, or period_unavailable. An owner can receive Keep full speed on credits, Add funds, Raise the key limit, Raise the cap, or Contact support as the next step. A member receives Ask an owner.

The funding headers report x-runinfra-funding: refused. /v1/messages rewrites the body to error.type: "billing_error" and the message text, with request_id; the other plan fields are absent. In Messages clients such as Claude Code, read the message: it carries the limit, reset, Standby condition, and next step without an error.code. See Messages.

Envelopes that carry more than the table

{
  "error": {
    "limit_cents": 5000,
    "spent_cents": 5000,
    "resets_at": "2026-10-01T00:00:00.000Z",
    "message": "This API key has reached its monthly spending limit of $50.00 ($50.00 settled this month). Raise or remove the limit under Settings, API keys, or wait for the month to reset at 2026-10-01T00:00:00.000Z.",
    "type": "permission_error",
    "param": null,
    "code": "spend_limit_reached"
  },
  "request_id": "req_example_0011"
}

{
  "error": {
    "original_status": 200,
    "original_response_bytes": 25000000,
    "message": "The original response for this Idempotency-Key was too large to replay safely. Do not retry with a new key because that can start new paid work. Contact support with the request ID.",
    "type": "invalid_request_error",
    "param": "Idempotency-Key",
    "code": "idempotency_replay_unavailable"
  },
  "request_id": "req_example_0012"
}

X-RunInfra-Idempotent-Replay: unavailable

{
  "error": {
    "message": "This model cannot enforce response_format while it is reasoning, so the reply would not match the format you asked for and the request would be billed anyway. Send \"reasoning_effort\": \"none\" together with response_format, or remove response_format. On /v1/responses the same remedy is a top-level \"reasoning_effort\": \"none\" beside \"text\": {\"format\": ...}.",
    "type": "invalid_request_error",
    "param": "response_format",
    "code": "hosted_parameter_not_supported"
  },
  "request_id": "req_example_0020"
}

{
  "error": {
    "message": "The gateway is at capacity and shed this request before completing it. This is a temporary condition on our side, not a problem with your request. Retry after the interval in the Retry-After header.",
    "type": "rate_limit_error",
    "param": null,
    "code": "hosted_admission_congested"
  },
  "request_id": "req_example_0018"
}

HTML 403 security checkpoint

An HTML 403 security checkpoint instead of a JSON error means automatic traffic protection flagged your network. The response carries x-vercel-mitigated: challenge. Wait a few minutes before retrying, lower the request burst, and contact support if it persists.

Payload too large

The 32MB ceiling is enforced on the declared Content-Length and again while the body streams, so an understated Content-Length does not bypass it. It is a limit on the encoded request and is separate from the model context window: split the prompt across requests or send less context.

A body above 32MB gets the same JSON 413 payload_too_large, with a request id, after the upload finishes. The one exception is a request above about 4MB that has no Content-Length header: the platform edge rejects it before the gateway sees it, with a 413 that carries no JSON envelope and no request id. Treat both as the same instruction: shrink the body, and send a Content-Length header (every SDK does).

Retry rules

• Keep the same Idempotency-Key when you retry, streaming or not.
• Respect Retry-After, or Retry-After-Ms if your client reads it, on every response that carries them.
• On the hosted admission 429 codes the value is an estimate, capped at 8 seconds, and it changes between refusals. Add jitter if many workers share one key.
• Do not replace the key after 422 idempotency_replay_unavailable.
• A streaming retry never replays the delivered tokens. The same key returns 409 while the original is open, then the terminal usage and cost once it settles. See Idempotent retries.

Related