Corriger OpenRouter 429 "Provider Returned Error" : rate limits, fournisseurs upstream et options de fallback

Ces deux erreurs se ressemblent dans vos logs mais ont des causes différentes :

• 429 Too Many Requests : votre requete a ete rejetee parce qu'un rate limit a ete atteint
• Provider returned error : OpenRouter a accepte votre requete mais le fournisseur upstream du modele (OpenAI, Anthropic, Google, etc.) a renvoye une erreur

Les confondre mene a de mauvaises corrections. Ce guide vous aide a isoler la cause et a choisir la bonne réponse.

En bref

• Un 429 d'OpenRouter signifie que vous avez atteint le rate limit ou le quota d'OpenRouter.
• Un "provider returned error" signifie que le fournisseur upstream a rejete la requete -- pas OpenRouter.
• Vérifiez les en-tetes de réponse et le corps de l'erreur pour distinguer les deux.
• La correction est différente : un 429 OpenRouter necessite des changements de clé ou de tier ; les erreurs de fournisseur necessitent un diagnostic upstream ou des changements de route.
• Pour les charges de travail en production, concevez le fallback avant que l'erreur ne survienne.

Etape 1 : Lire attentivement la réponse d'erreur

Lorsque vous recevez une erreur, examinez ces trois elements :

Un 429 OpenRouter typique ressemble a ceci :

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please slow down."
  }
}

Une erreur de fournisseur typique est différente :

{
  "error": {
    "code": 502,
    "message": "Provider returned error: [upstream error details]"
  }
}

La distinction est importante car les corrections requises sont différentes.

Etape 2 : Identifier la source de l'erreur

Utilisez cet arbre de decision :

Requete echouee
├── HTTP 429 + message de rate limit OpenRouter
│   → Cause : rate limit au niveau d'OpenRouter
│   → Solution : reduire le debit de requêtes, passer au tier superieur ou ajouter un delai
│
├── HTTP 429 + "provider returned error" dans le message
│   → Cause : rate limit du fournisseur upstream retransmis
│   → Solution : vérifiér le quota du fournisseur, changer de modele ou ajouter une route de fallback
│
├── HTTP 502/503 + "provider returned error"
│   → Cause : panne du fournisseur upstream ou defaillance transitoire
│   → Solution : reessayer avec backoff, changer de fournisseur ou utiliser un fallback
│
└── HTTP 400/401 + message d'erreur
    → Cause : requete invalide, clé invalide ou modele introuvable
    → Solution : vérifiér la clé API, l'ID du modele et le format de la requete

Etape 3 : Corriger le 429 au niveau d'OpenRouter

Si le 429 provient d'OpenRouter lui-meme (pas retransmis depuis un fournisseur), vérifiéz dans cet ordre :

3.1 Verifier votre tier de rate limit actuel

OpenRouter applique des rate limits en fonction du tier de votre compte. Les utilisateurs du tier gratuit ont des limites nettement inferieures a celles des utilisateurs payants.

3.2 Reduire le debit de requêtes

Si vous envoyez des requêtes plus vite que votre tier ne le permet :

import asyncio
import random

async def call_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                # Respect retry-after if present, otherwise use jittered backoff
                delay = min(30, (2 ** attempt) + random.random())
                await asyncio.sleep(delay)
            else:
                raise

3.3 Repartir le trafic dans le temps

Les charges de travail d'agents creent souvent des pics de requêtes. Au lieu d'envoyer 50 requêtes simultanement :

• Utilisez un semaphore pour limiter la concurrence
• Ajoutez un petit delai entre les lots
• Separarez les files d'attente de premier plan et d'arriere-plan

Etape 4 : Corriger les erreurs du fournisseur upstream

Si le message d'erreur contient "provider returned error", le problème se situe en amont. OpenRouter a transmis votre requete, mais le fournisseur du modele l'a rejetee.

4.1 Causes upstream courantes

4.2 Basculer vers une route de fournisseur différente

OpenRouter achemine les requêtes vers des fournisseurs upstream. Si un fournisseur vous limite, le meme modele pourrait etre disponible via un chemin de fournisseur different.

Vérifiez si :

• Le modele dispose de plusieurs options de fournisseur sur OpenRouter
• Vous pouvez configurer les preferences de fournisseur dans votre requete
• Un modele de fallback avec des capacites similaires est disponible

4.3 Ajouter une logique de reessai qui distingue les types d'erreur

Ne reessayez pas toutes les erreurs de la meme maniere :

async def smart_retry(make_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            error_msg = str(e)

            # Do NOT retry: bad request, auth error, model not found
            if any(code in error_msg for code in ["400", "401", "404"]):
                raise

            # Retry with backoff: rate limit or provider error
            if any(code in error_msg for code in ["429", "502", "503"]):
                delay = min(30, (2 ** attempt) + random.uniform(0, 1))
                await asyncio.sleep(delay)
            else:
                raise

Etape 5 : Concevoir le fallback en amont

En production, la question n'est pas de savoir si des erreurs upstream surviendront -- elles surviendront. La question est de savoir si votre systeme degrade gracieusement ou s'effondre.

Checklist de fallback

Quand envisager un gateway API unifie

Si vous construisez une logique de fallback par-dessus OpenRouter pour gerer les defaillances upstream, vous construisez en realite une couche de routage sur une couche de routage.

A ce stade, il peut etre plus simple d'utiliser un gateway qui gere le routage des fournisseurs, le fallback et la selection de modeles comme fonctionnalite integree, plutot que du code au niveau applicatif.

• Routage automatique entre les fournisseurs
• Renvoie le modele réellement utilise dans la réponse
• Format de requete compatible OpenAI -- aucune reecriture de code nécessaire
• Pas de frais de routage supplementaires

curl https://api.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "evolink/auto",
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ]
  }'

Cela n'elimine pas le besoin d'une logique de reessai cote client, mais deplace la selection de fournisseurs et le fallback hors de votre code applicatif.

Arbre des causes d'erreur (reference)

Requete OpenRouter echouee
│
├── 429 d'OpenRouter
│   ├── Limite du tier gratuit → passer au tier superieur
│   ├── Trafic en pic → ajouter un controle de concurrence
│   └── Volume eleve soutenu → vérifiér les limites du tier
│
├── "Provider returned error"
│   ├── Upstream 429
│   │   ├── Rate limit du fournisseur → reduire le debit ou changer de fournisseur
│   │   └── Quota partage epuise → vérifiér les limites au niveau de l'organisation
│   ├── Upstream 502/503
│   │   ├── Panne du fournisseur → vérifiér la page de statut, attendre ou changer
│   │   └── Defaillance transitoire → reessayer avec backoff
│   └── Upstream 400
│       ├── Contexte trop long → tronquer ou changer de modele
│       ├── Parametres invalides → vérifiér la documentation de l'API
│       └── Modele obsolete → vérifiér l'ID du modele
│
└── Autres erreurs
    ├── 401 → clé API invalide
    ├── 404 → modele introuvable
    └── Erreur réseau → vérifiér la connectivite

Prochaines étapes

1. Vérifiez votre erreur actuelle : Utilisez l'Etape 2 pour determiner s'il s'agit d'un 429 OpenRouter ou d'une erreur de fournisseur.
2. Appliquez la correction ciblee : N'appliquez pas les corrections de rate limit aux erreurs de fournisseur, et inversement.
3. Ajoutez une logique de reessai structuree : Distinguez dans le code les erreurs recuperables de celles qui ne le sont pas.
4. Concevez le fallback avant d'en avoir besoin : Les systemes de production ne doivent jamais dependre d'un seul chemin upstream.

Articles connexes

• How to Reduce 429 Errors in Agent Workloads -- modeles avances pour le trafic en pic spécifique aux agents
• Best OpenRouter Alternatives in 2026 -- comparer les options de routage quand les limites d'OpenRouter sont un problème recurrent
• Best AI API Platform for Production Reliability -- cadre de reference pour choisir une plateforme API de production fiable

FAQ

Que signifie "provider returned error" sur OpenRouter ?

Cela signifie qu'OpenRouter a recu votre requete et l'a transmise au fournisseur upstream du modele, mais que le fournisseur a renvoye une erreur. L'erreur ne provient pas d'OpenRouter lui-meme mais d'OpenAI, Anthropic, Google ou du fournisseur qui sert ce modele.

Un 429 d'OpenRouter est-il identique a un 429 du fournisseur upstream ?

Non. Un 429 au niveau d'OpenRouter signifie que vous avez atteint les rate limits propres d'OpenRouter. Un 429 au niveau du fournisseur retransmis comme "provider returned error" signifie que le fournisseur upstream a rejete la requete. Les corrections sont différentes.

Dois-je reessayer en cas de "provider returned error" ?

Cela dépend du type d'erreur. Si l'upstream a renvoye 502/503 (defaillance transitoire), reessayer avec backoff est raisonnable. S'il a renvoye 400 (requete invalide) ou 404 (modele introuvable), reessayer ne servira a rien -- corrigez plutot la requete.

Comment savoir si le problème vient de ma clé API, de mon quota ou du fournisseur ?

Vérifiez dans cet ordre : (1) Votre clé API est-elle valide ? Essayez une requete de test simple. (2) Consultez votre tableau de bord OpenRouter pour vérifiér l'utilisation du quota et des rate limits. (3) Si votre clé et votre quota sont corrects, l'erreur provient probablement du fournisseur upstream -- consultez le message d'erreur pour plus de details.

Un gateway API unifie peut-il eliminer les erreurs de fournisseur ?

Aucun gateway ne peut empecher les fournisseurs upstream de tomber en panne. Mais un gateway avec routage et fallback integres peut basculer automatiquement vers un fournisseur ou un modele alternatif lorsqu'un chemin echoue, reduisant ainsi l'impact sur votre application.

Quand devrais-je passer d'OpenRouter a une autre solution de routage ?