Limits

​

Checking your limits

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

    free_model_daily_requests: {
      used: number; // Free-model requests recorded so far in the current UTC day
      limit: number; // Free-model requests allowed per UTC day (see the free usage limits below)
      remaining: number; // Free-model requests left in the current UTC day
    };
    // rate_limit: { ... } // A deprecated object in the response, safe to ignore
  };
};

​

Credit limits

1. 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.
2. 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

• 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

1. Free usage limits: If you’re using a free model variant (with an ID ending in :), the following limits apply:

2. DDoS protection: Cloudflare’s DDoS protection will block requests that dramatically exceed reasonable usage.

​

Handling 429 errors

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "metadata": {
      "error_type": "rate_limit_exceeded"
    }
  }
}

1. OpenRouter, when you hit one of the platform limits above (free-model requests per minute or per day, or DDoS protection).
2. 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.

• 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

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"}]}