Fix an OpenRouter 402 Error and Negative Balance

An OpenRouter 402 is not a flaky network error. It means the request was refused because the account does not have enough credit. If the dashboard also shows a negative balance, stop the client first. Automatic retries will keep spending against a balance that is already below zero.

Recovery is three steps: stop the workload, add enough credit to get above zero, then send one small manual request before restarting the agent. The rest of this page explains why a prepaid-looking balance can cross zero, and how to keep the next incident inside a $5 or $10 key budget.

Which 402 message did you get? #

OpenRouter returns a few different 402 messages. Each one points at a different fix.

"This request requires more credits, or fewer max_tokens"

The full message reads like: *"This request requires more credits, or fewer max_tokens. You requested up to 64000 tokens, but can only afford 1600."* OpenRouter checks the most the request could cost, using its max_tokens, against your remaining credit. Coding agents often ask for 32K or 64K output tokens by default, so a small balance fails even for a short answer.

• Lower max_tokens for the request. In Claude Code, set CLAUDE_CODE_MAX_OUTPUT_TOKENS to a smaller value, such as 8000.
• Switch to a cheaper model for the same task.
• Or add credit so the balance covers the reserved output.

"Insufficient credits. This account never purchased credits"

The key belongs to an account or organization with no credit purchase on record. This is common when a key was created under a personal account but credits were bought for an organization, or the other way round. Check which account or org owns the key. If it is the right one, buy credits there. Free-model allowances do not cover paid models.

"Insufficient credits. Add more using https://openrouter.ai/settings/credits"

The available balance is at or below zero. If the dashboard shows a negative balance, usage posted after the balance check (see below). Stop the client before topping up, or queued retries will spend the new credit straight away.

If you are deciding whether the failure mode justifies switching services, separate the incident from the purchase model. The OpenRouter credits and fee guide covers funding cost and expiry terms, while the OpenRouter alternatives comparison compares hosted wallets including LLM Gateway and Vercel AI Gateway.

Why a balance can cross zero #

LLM billing is finalized after tokens are generated. At request start, a gateway knows the current balance and an estimate of what the request might cost. It does not yet know the final output length.

Several normal API behaviors can create a small accounting gap:

• Streaming: the response starts before the final output-token count is known.
• Concurrency: multiple requests pass the same pre-request balance check at nearly the same time.
• Retries: an SDK, proxy, or agent may retry a request without making the retry obvious in the UI.
• Long outputs: a missing or high max_tokens value lets a response cost much more than expected.
• Agent loops: tools can call the model repeatedly until a task ends, multiplying a small per-call cost.
• Delayed usage posting: provider usage can arrive after the response completes.

Imagine an account with $0.08 left and four concurrent requests. Each request sees a positive balance at the start. If each eventually costs $0.04, the final combined cost is $0.16 and the resulting balance is -$0.08.

How to recover from a 402 #

1. Stop the process that is sending requests. Do not let an automatic retry loop keep firing.
2. Open the activity or usage log and filter to the affected API key and time window.
3. Check whether requests were concurrent, retried, or unexpectedly long.
4. Rotate the key if the traffic is not yours.
5. Add enough credit to restore a positive available balance.
6. Send one small request manually before restarting the full workload.

For an automated service, treat a 402 as a billing-state error, not a transient network error. Blind exponential retries cannot create credit and may hide the actual failure from an operator.

from openai import OpenAI, APIStatusError
 
client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="sk-...",
)
 
try:
    client.chat.completions.create(
        model="your-model",
        messages=[{"role": "user", "content": "Summarize this file"}],
        max_tokens=500,
    )
except APIStatusError as error:
    if error.status_code == 402:
        # Alert an operator and pause the queue. Do not auto-retry forever.
        raise RuntimeError("LLM credit exhausted") from error
    raise

Four controls that matter more than a low-balance alert #

An alert is useful, but it fires after spend has already happened. Stronger controls stop or constrain the request path.

1. One key per workload

Do not share the same key across production, local development, CI, and coding agents. Separate keys make attribution and revocation straightforward.

2. A hard key budget

A server-side key budget is better than a dashboard target. Set the maximum amount that a key is allowed to consume. If a local experiment should cost at most $10, its credential should not be able to reach the other $490 in the account.

3. Output and concurrency limits

Set max_tokens, bound the number of parallel requests, and cap agent steps. These limits reduce both expected cost and the uncertainty between request start and final accounting.

4. Fail closed when balance data is unavailable

If your own service cannot retrieve the current gateway balance, do not display a made-up zero or assume the full lifetime top-up remains available. Mark the balance unavailable and pause high-risk jobs until billing state is trustworthy.

The prepaid design alternative #

RouterPlex uses a prepaid account balance and lets every API key carry a hard lifetime spend budget. Requests stop when the balance reaches $0 instead of turning into a negative amount that must be repaid. When credit runs out, the API returns a 402 whose message says the balance is used up and links straight to the top-up page, so a coding agent does not sit in a retry loop.

New accounts can connect Claude Code, Cursor, Codex or another OpenAI-compatible tool in guided setup and test it with $1 of credit before paying. Top-ups start at $5 and the credit does not expire.

The safest setup still uses defense in depth: a $10 key budget, explicit output limits, bounded concurrency, and a low-balance alert. No single billing check can replace application-level controls for an autonomous agent.

For the exact setup, read API keys and budgets. You can also compare RouterPlex and OpenRouter directly, or create a $5 prepaid account and test the failure behavior with a deliberately small key budget.