OpenRouter 429 rate_limit_exceeded: what it means and how to fix it

What it means

A request- or token-level rate limit was hit. It can come from OpenRouter (free-model limits of 20 requests per minute and 50 or 1000 requests per day, or DDoS protection) or from the upstream provider, in which case error.metadata.provider_code carries the provider's code. If hit after streaming starts, it arrives as an SSE event with finish_reason error instead of HTTP 429.

Causes

• Free model variant (:free) per-minute or per-day request cap
• Cloudflare DDoS protection blocking requests that dramatically exceed reasonable usage
• Upstream provider rate limiting or at capacity

How to fix it

1. 1
   Fix 1.

   Retry with exponential backoff and honor the Retry-After header when present.

   Snippet

   Copy

   const res = await fetch('https://openrouter.ai/api/v1/chat/completions', { ... });
   if (res.status === 429 || res.status === 503 || res.status === 402) {
     const retryAfter = Number(res.headers.get('Retry-After'));
     if (Number.isFinite(retryAfter) && retryAfter > 0) {
       await new Promise((r) => setTimeout(r, retryAfter * 1000));
       // retry the request
     }
   }

2. 2
   Fix 2.

   On free variants, purchase at least 10 credits to raise the daily limit, or switch to the paid variant of the model.

3. 3
   Fix 3.

   For provider-side limits, add fallback models or relax provider routing preferences so more providers are eligible.