OpenRouter 429 Rate Limit Exceeded — How to Diagnose and Fix It

Before touching your code, confirm the 429 is not an active incident — either on OpenRouter itself or on the upstream provider it routes to. A 429 (or a surge of them) during an outage means the right move is to wait and retry, not rewrite your retry logic.

OpenRouter is OpenAI-compatible, so you use the OpenAI SDK pointed at https://openrouter.ai/api/v1 with your OPENROUTER_API_KEY. When a 429 comes back, log the JSON body and its error.metadata — if it names an upstream provider, the downstream model rate-limited you; if it does not, it is OpenRouter's own cap.

# Python — inspect a 429 to see where the limit came from
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

try:
    resp = client.chat.completions.create(
        model="deepseek/deepseek-r1:free",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(resp.choices[0].message.content)
except APIStatusError as e:
    if e.status_code == 429:
        # error.metadata usually names the upstream provider when the
        # limit came from downstream; if absent, it is OpenRouter's cap.
        print("429 rate limited. Body:", e.response.text)
        print("Retry-After:", e.response.headers.get("Retry-After"))
    else:
        raise

// TypeScript — same idea
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY,
});

try {
  const resp = await client.chat.completions.create({
    model: 'deepseek/deepseek-r1:free',
    messages: [{ role: 'user', content: 'Hello' }],
  });
  console.log(resp.choices[0].message.content);
} catch (e) {
  if (e instanceof OpenAI.APIError && e.status === 429) {
    // e.error.metadata names the upstream provider when the limit
    // was passed through; otherwise it is OpenRouter's own cap.
    console.warn('429 rate limited', e.error);
    console.warn('Retry-After', e.headers?.['retry-after']);
  } else {
    throw e;
  }
}

The :free variants share a small capacity pool and carry strict per-minute and per-day caps — they are meant for testing, not production. The fastest fix is to drop the :free suffix and use the paid variant. Adding credits also helps twice over: your overall rate ceiling scales with your balance, and the daily allowance on free models scales with your lifetime credits purchased.

# Heavily rate-limited (shared free pool):
model = "deepseek/deepseek-r1:free"

# Paid variant — much higher limits, pay-per-token:
model = "deepseek/deepseek-r1"

resp = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Hello"}],
)

• Raise your ceiling: add credits at openrouter.ai/credits. A near-zero balance keeps you in the lowest rate bracket even on paid models.
• Watch the exact limits: published caps change over time — check your current per-key limits in the OpenRouter dashboard rather than hard-coding a number.

Transient 429s clear on their own if you wait and retry. Wrap the call in a retry loop that honors the Retry-After header when OpenRouter sends one, and otherwise backs off exponentially with jitter, capped at 60 seconds:

import os, time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://openrouter.ai/api/v1",
                api_key=os.environ["OPENROUTER_API_KEY"])

def create_with_backoff(max_attempts: int = 6, **kwargs):
    """Retry on 429 with Retry-After, else exponential backoff + jitter."""
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except APIStatusError as e:
            if e.status_code != 429 or attempt == max_attempts - 1:
                raise  # 402/401/400 are not retriable; give up on last try
            retry_after = e.response.headers.get("Retry-After")
            wait = float(retry_after) if retry_after else min(
                60.0, (2 ** attempt) + random.uniform(0, 1))
            print(f"429 — retry {attempt + 1}/{max_attempts - 1} in {wait:.1f}s")
            time.sleep(wait)

response = create_with_backoff(
    model="deepseek/deepseek-r1",
    messages=[{"role": "user", "content": "Hello"}],
)

// TypeScript async version
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY,
});

async function createWithBackoff(
  params: OpenAI.ChatCompletionCreateParamsNonStreaming,
  maxAttempts = 6,
) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await client.chat.completions.create(params);
    } catch (e) {
      if (!(e instanceof OpenAI.APIError) || e.status !== 429) throw e;
      if (attempt === maxAttempts - 1) throw e;
      const retryAfter = Number(e.headers?.['retry-after']);
      const wait = retryAfter
        ? retryAfter * 1000
        : Math.min(60_000, (2 ** attempt) * 1000 + Math.random() * 1000);
      console.warn(`429 — retry ${attempt + 1} in ${(wait / 1000).toFixed(1)}s`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

When the 429 comes from an upstream provider, the best fix is to let OpenRouter route around it. Set provider.allow_fallbacks so a rate-limited or overloaded provider is automatically retried on another that serves the same model. You can also pass a models array to fall back across different models in order. With the OpenAI SDK these OpenRouter extensions go in extra_body (Python) or as extra request fields (TypeScript):

# Python — OpenRouter provider routing + model fallback
resp = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        # Fall back across models in order if one is unavailable:
        "models": [
            "deepseek/deepseek-r1",
            "anthropic/claude-3.5-sonnet",
        ],
        # Provider-level routing: let OpenRouter retry another upstream
        # that serves the same model when one is rate-limited / down.
        "provider": {
            "allow_fallbacks": True,
        },
    },
)

// TypeScript — same routing fields on the request body
const resp = await client.chat.completions.create({
  model: 'deepseek/deepseek-r1',
  messages: [{ role: 'user', content: 'Hello' }],
  // OpenRouter extensions (not in the base OpenAI types):
  // @ts-expect-error
  models: ['deepseek/deepseek-r1', 'anthropic/claude-3.5-sonnet'],
  provider: { allow_fallbacks: true },
});

• Combine layers: provider fallback handles a single bad upstream; client-side backoff (Step 4) handles the case where every route is momentarily busy. Use both.
• Always honor Retry-After: when OpenRouter or an upstream sends the header, waiting exactly that long is more reliable than guessing.