OpenRouter Credits: Expiration, Balance API and Error Fixes

What Are OpenRouter Credits?

OpenRouter credits are prepaid units deducted when you call models through the OpenRouter API. They are not the same as a provider's native account balance, and they are separate from per-key spending limits. Treat this page as educational background, not as official OpenRouter documentation.

Do OpenRouter Credits Expire?

OpenRouter's current FAQ (reviewed June 25, 2026) states:

"OpenRouter reserves the right to expire unused credits after one year of purchase."

This means you should not assume a purchased credit balance remains valid indefinitely. The official wording is "reserves the right" — it should not be rewritten as a guarantee that every balance is automatically removed on an exact date. Before relying on an older credit balance, check the current OpenRouter FAQ, account notices and purchase records.

Do not use phrases like "credits never expire" or "credits are permanently valid." These contradict the official FAQ. If you see conflicting information elsewhere, treat the current OpenRouter FAQ as the authoritative source.

What "After One Year" Actually Means

OpenRouter's FAQ says it reserves the right to expire unused credits after one year of purchase. The documentation does not promise that every balance expires automatically on an exact date, nor does it document a detailed package-by-package expiry schedule on the FAQ page. Check the current FAQ, Terms and account balance before relying on old credits.

How to Check Your OpenRouter Credit Balance via API

Three views help you track your credit balance:

• Account dashboard — the primary balance view, including purchase history
• Activity page — per-request usage records, timestamps and credit deductions
• Credits API — GET /api/v1/credits with a management key, returning total_credits and total_usage

Compare all three views when reconciling an unexpected balance change. No single view tells the whole story on its own.

Credits API Example

The documented endpoint:

GET https://openrouter.ai/api/v1/credits
Authorization: Bearer <management-key>

Documented response fields:

• total_credits — total purchased credit amount in USD
• total_usage — cumulative amount spent

Note: do not look for balance, remaining_balance or remaining_credits — these fields are not documented in the official API reference. total_credits - total_usage gives a rough remaining estimate, but the Activity page and dashboard provide the authoritative balance.

Do not paste a management key into an untrusted browser tool, screenshot or support message.

Account Credits vs API Key Spending Limits

Account credits and API-key spending limits are different controls. Account credits fund model access. API-key spending limits cap how much an individual key can consume. A key can be valid but still blocked by its spending limit even when the account balance is not fully depleted. Check both the account-level balance and the key-level limit before assuming a single cause for a failed request.

total_credits vs total_usage

These two fields serve different reconciliation purposes:

• total_credits — cumulative credits purchased over the account lifetime
• total_usage — cumulative spend deducted from that balance

To estimate a rough remaining balance: total_credits − total_usage. This is an approximation because it does not account for refunds, credits, promotional balances, or expiry of older unused credits. Cross-reference with the Activity page for the authoritative per-request view.

How to Fix a 402 Insufficient Credits Error

HTTP 402 generally indicates the account or API key does not have enough credits for the requested operation. Start by checking the account balance and the affected key's spending limit, then inspect the request parameters that can increase cost, such as very large max_tokens values.

• ✓Inspect the actual HTTP status code and JSON error body
• ✓Check account credits and the API key spending limit
• ✓Review recent requests for unexpectedly large token counts
• ✓Compare the Activity page against local request logs
• ✓Do not blindly retry 402 responses without changing the underlying cause

OpenRouter 402 vs 403 vs 429

These three status codes are often confused. They mean different things:

402 vs 403: do not write that insufficient credits return 403. The current OpenRouter error documentation explicitly assigns insufficient credits to 402. HTTP 403 covers permission failures, guardrails and moderation blocks.

402 vs 429: a 429 response means you have sent too many requests in a time window. It does not mean the account is out of credits. Check the Retry-After header before resuming. A negative balance account may see 402 on free models too — check the limits documentation.

How to Diagnose 403 and Provider Terms Restrictions

This error is not a credit-balance issue. According to OpenRouter's error documentation, HTTP 403 covers insufficient permissions, guardrail blocks and moderation flags. A request blocked for terms-of-service reasons falls into one of these categories on the upstream provider side.

What this error typically means:

• The upstream provider's content policy flagged the request content
• A guardrail configured on the account blocked the request before it reached the model
• The request content or attachments violate the provider's acceptable-use policy
• The account with the upstream provider has a restriction

Check these when investigating the error:

• Provider and model — which provider and model slug generated the error
• Request content — inspect the input messages, system prompt and attachments for policy-sensitive material
• Error metadata — error.metadata may contain a reason or provider_name field
• Moderation output — if the error relates to a moderation flag, the response may include the specific flagged segment
• Request ID — record the request_id from the error response for support escalation

What this error does not mean:

• It is not a credit-balance problem; HTTP 402 covers insufficient credits
• It is not a rate-limit problem; HTTP 429 covers rate limits
• Switching providers or models does not guarantee the same content will pass elsewhere — each provider has its own acceptable-use policy
• Automatically retrying the same request across multiple providers may generate the same error and multiply credit charges on a pay-per-request basis

Do not attempt to circumvent a provider's terms-of-service policy. If a request has been flagged, revise the content to comply with the provider's policy rather than attempting to route around the block.

Auto Top-Up, Usage Monitoring and Refund Considerations

OpenRouter supports optional Auto Recharge, which can automatically add credits when the balance falls below a configured threshold. Auto Recharge is separate from a recurring subscription and can be changed or disabled from the Credits page at any time. Monitor your balance proactively; do not rely on Auto Recharge as the sole mechanism for maintaining a credit balance.

Use the Activity page, the account dashboard and the credits API together for usage tracking. Review the OpenRouter documentation for the current Auto Recharge settings and any associated billing terms.

Refund and billing dispute questions should be directed to OpenRouter's support channels. Check the current OpenRouter terms for refund eligibility and dispute procedures before raising a support request. This page cannot substitute for OpenRouter's current terms or support responses.

"Your Prepayment Credits Are Depleted" Troubleshooting

If a client or SDK displays the message "your prepayment credits are depleted," treat it as a balance-depletion signal. However:

• Inspect the actual HTTP status code in the response
• Read the JSON error body for the documented error.code or error.type
• OpenRouter documents insufficient-credit failures as HTTP 402, not 403
• Check whether the affected API key has a spending limit configured
• Review the Activity page for unexpected large deductions
• Do not assume every client or SDK surfaces the exact same error text

Usage, Activity Records and Reconciliation

OpenRouter automatically includes usage details in every API response: prompt tokens, completion tokens, cost, reasoning tokens (if applicable), cached tokens and cache write tokens. You do not need to add usage: { include: true } or stream_options: { include_usage: true } — these are deprecated.

Use this checklist when reconciling credit deductions:

• ✓Record request_id and timestamp for every API call
• ✓Read the response usage.cost field for per-request credit deduction
• ✓Compare prompt, completion, reasoning and cached-token fields across requests
• ✓Check the selected model and provider route for each request
• ✓Compare the Activity page against local request logs
• ✓Check total_credits and total_usage via the credits API when you have a management key
• ✓Review API key spending limits
• ✓Identify retries, parallel jobs or duplicate requests
• ✓Do not blindly retry 402 or 429 responses

Why Credits May Drop Faster Than Expected

• Model switching mid-workflow — different models have different per-token or per-request costs
• Provider routing — OpenRouter may route to different underlying providers with different pricing
• Long context — large input or output token counts multiply cost; agents replaying conversation history are especially affected
• Retries and failed requests — OpenRouter's current pricing FAQ says failed or fallback attempts are not billed and that routing or fallback charges apply only to successful model runs. For an ambiguous partial or streaming response, inspect usage.cost and the Activity record rather than assuming a charge.
• Tool calls and agent workflows — multi-step workflows accumulate token overhead quickly
• Parallel sessions — running several agent instances simultaneously multiplies credit usage

Use the AI API Cost Benchmark to turn expected usage into an estimated monthly cost before adding a large balance.

Small Prepaid Test Checklist

• ✓Start with a small credit package — do not scale on a large balance before testing
• ✓Test with the specific model and provider you plan to use in production
• ✓Record request_id, usage.cost and timestamp for each test request
• ✓Compare actual credit deduction against the expected cost estimate
• ✓Check the Activity page and compare against your local records
• ✓Scale gradually while monitoring balance

Official Sources Reviewed

Last reviewed: June 25, 2026

• https://openrouter.ai/docs/faq
• https://openrouter.ai/docs/api/reference/errors-and-debugging
• https://openrouter.ai/docs/api/api-reference/credits/get-credits
• https://openrouter.ai/docs/api/reference/limits

AICostPlanner is an independent educational cost-planning site and is not affiliated with OpenRouter.

Related Guides

OpenRouter Credits FAQ