[metadata]
apple-mobile-web-app-title: OpenRouter | Documentation
application-name: OpenRouter | Documentation
description: Credit Limits and Rate Limits
generator: Mintlify
msapplication-TileColor: #7624F4
msapplication-config: /docs/_mintlify/favicons/openrouter-d02e98a0/EmhfYwFO2tvnkuV-/_generated/favicon/browserconfig.xml
og:description: Learn about OpenRouter's credit limits (402) and rate limits (429), free-model quotas, and DDoS protection. Monitor usage and handle limit errors effectively.
og:image: https://openrouter.ai/dynamic-og?title=API%20Credit%20%26%20Rate%20Limits&description=Handle%20402%20and%20429%20Errors
og:image:height: 630
og:image:width: 1200
og:site_name: OpenRouter Documentation
og:title: API Credit & Rate Limits - Handle 402 and 429 Errors
og:type: website
og:url: https://openrouter.ai/docs/api_reference/limits
twitter:card: summary_large_image
twitter:description: Learn about OpenRouter's credit limits (402) and rate limits (429), free-model quotas, and DDoS protection. Monitor usage and handle limit errors effectively.
twitter:image: https://openrouter.ai/dynamic-og?title=API%20Credit%20%26%20Rate%20Limits&description=Handle%20402%20and%20429%20Errors
twitter:image:height: 630
twitter:image:width: 1200
twitter:title: API Credit & Rate Limits - Handle 402 and 429 Errors
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://openrouter.ai/docs/api_reference/limits

[document-links]
/docs/llms.txt: /docs/llms.txt
API Changelog: /docs/changelog
API Reference: /docs/api_reference/overview
API Versioning: /docs/api_reference/versioning
Agent SDK: /docs/agent-sdk/overview
Apps: https://openrouter.ai/apps
Authentication: /docs/api_reference/authentication
Benchmarks: https://openrouter.ai/benchmarks
Chat: https://openrouter.ai/chat
Client SDKs: /docs/client-sdks/overview
Cookbook: /docs/cookbook/get-started/quickstart
Docs: /docs/quickstart
Docs: https://openrouter.ai/docs
Embeddings: /docs/api_reference/embeddings
Errors and Debugging: /docs/api_reference/errors-and-debugging
Handling Errors During Streaming: /docs/api_reference/streaming#handling-errors-during-streaming
Limits: /docs/api_reference/limits
Models: https://openrouter.ai/models
OpenRouter | Documentation home page: https://openrouter.ai
Overview: /docs/api_reference/overview
Parameters: /docs/api_reference/parameters
Rankings: https://openrouter.ai/rankings
Streaming: /docs/api_reference/streaming
error response: /docs/api_reference/errors-and-debugging
fallback models: /docs/guides/routing/model-fallbacks
fallback routing: /docs/guides/routing/provider-selection
provider routing preferences: /docs/guides/routing/provider-selection

[structured-data]
{"@context":"https://schema.org","@graph":[{"@id":"https://openrouter.ai/#organization","@type":"Organization","logo":{"@type":"ImageObject","url":"https://mintcdn.com/openrouter-d02e98a0/ksNSeB_K7gD-BUDh/assets/logo-v2-light.svg?fit=max&auto=format&n=ksNSeB_K7gD-BUDh&q=85&s=690e45873843519efe02bcbe45795dac"},"name":"OpenRouter | Documentation","url":"https://openrouter.ai"},{"@id":"https://openrouter.ai/docs#website","@type":"WebSite","name":"OpenRouter | Documentation","publisher":{"@id":"https://openrouter.ai/#organization"},"url":"https://openrouter.ai/docs"},{"@id":"https://openrouter.ai/docs/api_reference/limits#webpage","@type":"WebPage","breadcrumb":{"@id":"https://openrouter.ai/docs/api_reference/limits#breadcrumb"},"dateModified":"2026-08-08T19:05:56.646Z","description":"Credit Limits and Rate Limits","isPartOf":{"@id":"https://openrouter.ai/docs#website"},"name":"Limits","url":"https://openrouter.ai/docs/api_reference/limits"},{"@id":"https://openrouter.ai/docs/api_reference/limits#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://openrouter.ai/docs/api_reference/overview","name":"API Guides","position":1},{"@type":"ListItem","item":"https://openrouter.ai/docs/api_reference/limits","name":"Limits","position":2}]},{"@id":"https://openrouter.ai/docs/api_reference/limits#article","@type":["Article","TechArticle"],"dateModified":"2026-08-08T19:05:56.646Z","description":"Credit Limits and Rate Limits","headline":"Limits","image":"https://openrouter.ai/dynamic-og?title=API%20Credit%20%26%20Rate%20Limits&description=Handle%20402%20and%20429%20Errors","isPartOf":{"@id":"https://openrouter.ai/docs#website"},"mainEntityOfPage":{"@id":"https://openrouter.ai/docs/api_reference/limits#webpage"},"name":"Limits","publisher":{"@id":"https://openrouter.ai/#organization"},"url":"https://openrouter.ai/docs/api_reference/limits"}]}

[content]
API Credit & Rate Limits - Handle 402 and 429 Errors
Documentation Index
Fetch the complete documentation index at:
/docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
OpenRouter | Documentation
home page
Search...
⌘
K
Ask Assistant
Models
Benchmarks
Chat
Rankings
Apps
Docs
Search...
Navigation
API Guides
Limits
Docs
API Reference
Client SDKs
Agent SDK
Cookbook
API Guides
Overview
Streaming
Embeddings
Limits
Authentication
Parameters
Errors and Debugging
Responses API
Versioning
API Versioning
API Changelog
API Reference
Analytics
TTS
STT
OAuth
Benchmarks
BYOK
Chat
Classifications
Credits
Datasets
Embeddings
Endpoints
Generations
Guardrails
Images
API Keys
Anthropic Messages
Models
Observability
Organization
Presets
Providers
Rerank
Responses
SCIM
Video Generation
Workspaces
On this page
Checking your limits
Credit limits
Handling 402 errors
Rate limits
Handling 429 errors
Mid-stream rate limits
API Guides
Limits
Copy page
Copy page
Credit Limits and Rate Limits
Copy page
Copy page
Making additional accounts or API keys will not affect your rate limits, as we govern capacity globally. We do however have different rate limits for different models, so you can share the load that way if you do run into issues.
OpenRouter enforces two kinds of limits:
Limit type
What it governs
Error on exceeding
Where to check
Credit limits
How much you can spend (account balance and per-key credit caps)
GET /api/v1/key
→
limit_remaining
Rate limits
How many requests you can make (free-model request caps and DDoS protection)
X-RateLimit-*
headers on the error response
​
Checking your limits
To check the rate limit or credits left on an API key, make a GET request to
https://openrouter.ai/api/v1/key
.
If you submit a valid API key, you should get a response of the form:
TypeScript
type
Key
=
{
data
:
{
label
:
string
;
limit
:
number
|
null
;
// Credit limit for the key, or null if unlimited
limit_reset
:
string
|
null
;
// Type of limit reset for the key, or null if never resets
limit_remaining
:
number
|
null
;
// Remaining credits for the key, or null if unlimited
include_byok_in_limit
:
boolean
;
// Whether to include external BYOK usage in the credit limit
usage
:
number
;
// Number of credits used (all time)
usage_daily
:
number
;
// Number of credits used (current UTC day)
usage_weekly
:
number
;
// ... (current UTC week, starting Monday)
usage_monthly
:
number
;
// ... (current UTC month)
byok_usage
:
number
;
// Same for external BYOK usage
byok_usage_daily
:
number
;
byok_usage_weekly
:
number
;
byok_usage_monthly
:
number
;
is_free_tier
:
boolean
;
// Whether the user has paid for credits before
// rate_limit: { ... }
// A deprecated object in the response, safe to ignore
};
};
See all 22 lines
​
Credit limits
Credit limits govern how much you can spend. They come from two places:
Account balance
, your available credits across the account. If your account has a negative credit balance, you may see
errors, including for free models. Adding credits to put your balance above zero allows you to use those models again.
Per-key credit limits
, an optional spending cap configured on an individual API key. The
limit
,
limit_reset
, and
limit_remaining
fields in the
GET /api/v1/key
response above describe this cap and how much of it remains.
​
Handling 402 errors
To resolve
errors:
Add credits
to bring your account balance above zero.
Check per-key limits.
If
limit_remaining
on the key is exhausted, raise the key’s credit limit or wait for it to reset (see
limit_reset
).
Monitor proactively.
Call
GET /api/v1/key
as shown above to track
limit_remaining
and usage before requests start failing.
​
Rate limits
Rate limits govern how many requests you can make. There are a few rate limits that apply to certain types of requests, regardless of account status:
Free usage limits
: If you’re using a free model variant (with an ID ending in
), the following limits apply:
Credits purchased (all time)
Requests per minute
Requests per day
Less than
At least
DDoS protection
: Cloudflare’s DDoS protection will block requests that dramatically exceed reasonable usage.
​
Handling 429 errors
Requests rejected with
fail with a standard
error response
:
{
"error"
: {
"code"
:
429
,
"message"
:
"Rate limit exceeded"
,
"metadata"
: {
"error_type"
:
"rate_limit_exceeded"
}
}
}
A
error can come from two places:
OpenRouter
, when you hit one of the platform limits above (free-model requests per minute or per day, or DDoS protection).
The upstream provider
, when the provider serving your request is rate limiting or at capacity. In this case
error.metadata.provider_code
carries the provider’s original error code when available, and
fallback routing
retries other providers for the same model automatically before the error reaches you. You can also specify
fallback models
to try a different model when all providers for the first are exhausted.
Successful inference responses do not include
X-RateLimit-*
headers. When OpenRouter itself returns a
error for a platform limit, the error response carries
X-RateLimit-Limit
,
X-RateLimit-Remaining
, and
X-RateLimit-Reset
headers describing the limit that was hit. When every attempted provider returned a retry hint, the error response also carries a
Retry-After
header. To monitor your remaining quota before hitting a limit, call
GET /api/v1/key
as shown above.
To resolve
errors:
Retry with exponential backoff.
Rate limits are transient; wait and retry rather than immediately re-sending. Honor the
Retry-After
header when present.
On free variants
, purchase at least
credits to raise your daily limit, or switch to the paid variant of the model, which has no platform-level request cap.
For provider-side limits
, add
fallback models
or relax
provider routing preferences
so more providers are eligible to serve the request.
​
Mid-stream rate limits
If a rate limit is hit after streaming has started, the error arrives as an SSE event with
finish_reason: "error"
instead of an HTTP
, since the
status was already sent:
data: {"id":"cmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"openai/gpt-4o","provider":"openai","error":{"code":429,"message":"Rate limit exceeded"},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}
See
Handling Errors During Streaming
for details and code examples.
Embeddings
Authentication
⌘
I
Assistant
Responses are generated using AI and may contain mistakes.
