OpenRouter 429 and 402 errors: what they mean and how to fix them

Short answer: on OpenRouter, 429 means a rate limit (OpenRouter’s own, or the upstream provider’s) and 402 means a credit problem (balance, the key’s credit limit, or the in-flight spending budget). For both, read error.metadata in the JSON body and the Retry-After header before you retry. Everything below is quoted from OpenRouter’s errors and limits docs, read on Nov 2, 2026.

OpenRouter error codes at a glance

Errors come back as JSON in the shape { error: { code, message, metadata } }, and the HTTP status matches error.code when the request itself is invalid or you are out of credits.

OpenRouter 429: “Rate limit exceeded”

A 429 can come from two places:

• OpenRouter’s platform limits. Free model variants (IDs ending in :free) allow 20 requests per minute, and 50 requests per day if you have bought less than 10 credits in total, or 1,000 per day once you have bought at least 10. Cloudflare’s DDoS protection also blocks traffic that is far above reasonable use.
• The upstream provider. When the provider serving your model is rate limiting or at capacity, error.metadata.provider_code carries its original code when available. OpenRouter’s fallback routing already retries other providers for the same model before the error reaches you.

What OpenRouter recommends:

1. Retry with exponential backoff, and honor the Retry-After header when it is present.
2. On free variants, buy at least 10 credits to raise the daily cap, or switch to the paid variant of the model, which has no platform-level request cap.
3. For provider-side limits, add fallback models or relax your provider routing preferences so more providers can serve the request.

Creating more accounts or API keys does not raise your limits: OpenRouter says it governs capacity globally, with different rate limits per model. If the limit is hit after streaming has started, you get an SSE event with finish_reason: "error" instead of an HTTP 429, because the 200 status was already sent.

OpenRouter 402: “Payment required” / insufficient credits

A 402 is about credits, not rate. Check error.metadata.limit_source to see which case you hit:

The in-flight budget exists because OpenRouter charges a request when it finishes: it estimates each paid request’s token cost up front and holds it against your balance while requests run. It applies only to some prepaid accounts (balances below a threshold, and newer accounts during the rollout), not to free models, pure BYOK requests, or enterprise and invoice-billed accounts. A negative balance can return 402 even on free models. None of the official SDKs retries a 402 on its own, so for the in-flight case catch it, read Retry-After and retry yourself. A 402 without that header is not a wait-and-retry case.

To see trouble coming, call GET https://openrouter.ai/api/v1/key: it returns limit_remaining, usage, budgets and the free-model daily counter for the key.

402 vs 403: budgets set by an org admin

If a guardrail budget, a workspace budget or the key’s own limit is spent, OpenRouter answers 403, not 402, before the request reaches a provider. The message ends with the figures (for example “$52.00 of $50.00 used; resets …”) and error.metadata.resets_at says when the window rolls over (UTC). There is no Retry-After, because the wait is usually hours or days.

A retry rule that covers both

const res = await fetch('https://openrouter.ai/api/v1/chat/completions', { ... })
if ([429, 503, 402].includes(res.status)) {
  const wait = Number(res.headers.get('Retry-After'))
  if (Number.isFinite(wait) && wait > 0) {
    // 429/503, or a 402 from the in-flight budget: wait, then retry
  } else if (res.status === 402) {
    // credits or key limit: retrying won't help; add credits or raise the key limit
  }
}

Also check the body of a 200: once a provider has accepted the request, later failures (including provider rate limits) arrive inside the response or stream with an error object and error.metadata.error_type, such as rate_limit_exceeded or payment_required.

HTTP 402 outside OpenRouter: x402

OpenRouter uses 402 to say “top up your credits”. Under the x402 protocol, a 402 is the price itself: the API answers with machine-readable payment terms, the agent pays per request in USDC and retries, with no account or prepaid balance. If you want models an agent can pay that way, see OpenRouter alternatives you can pay per call over x402.

Related

• OpenRouter pricing: fees, plans and USDC
• OpenRouter review
• OpenRouter alternatives (x402)

Sources

• OpenRouter: Errors and debugging
• OpenRouter: Limits (credit, budget and rate limits)

Checked Nov 2, 2026. OpenRouter changes limits often: confirm on its docs. We don’t monitor OpenRouter’s uptime; for outages use its official status page.