Erreurs, limites de débit et fiabilité
Intermédiaire
- Lire la carte des erreurs HTTP et savoir quels statuts réessayer plutôt que corriger
- Réessayer les erreurs transitoires avec un backoff exponentiel et du jitter, plafonné
- Gérer les limites de débit avec retry-after, lissage, traitement par lots et modèles moins chers
- Isoler votre code des dépréciations et migrations de modèles
Le code de production dialogue avec un service réseau ; il doit donc s'attendre aux échecs. Un peu de structure ici, c'est la différence entre une intégration instable et une intégration fiable.
La carte des erreurs
Les statuts HTTP typiques que vous gérerez :
| Statut | Signification | Que faire |
|---|---|---|
| 400 | Requête invalide | Corrigez la charge utile ; ne réessayez pas telle quelle |
| 401 | Clé API absente/incorrecte | Vérifiez les identifiants |
| 403 | Non autorisé | Vérifiez l'accès/les permissions |
| 429 | Limite de débit atteinte | Faites un backoff et réessayez (respectez retry-after) |
| 500/529 | Erreur serveur / surcharge | Réessayez avec backoff |
- Les SDK exposent ces erreurs comme des exceptions typées, ce qui vous permet de brancher proprement au lieu d'analyser des chaînes de caractères.
Nouvelles tentatives avec backoff
Pour les erreurs transitoires (429, 5xx), réessayez avec un backoff exponentiel + jitter, plafonné :
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
- De nombreux SDK réessaient automatiquement les erreurs transitoires — connaissez le comportement par défaut de votre client avant d'ajouter le vôtre, sinon vous risquez de doubler les tentatives.
Limites de débit
Les limites s'appliquent par compte/palier (requêtes et tokens par minute). Quand vous en atteignez une, vous obtenez un 429 avec des indications de timing. Stratégies pour rester sous le plafond :
Guided walkthrough1 of 4
- Quand vous obtenez un 429, lisez l'indication de timing dans la réponse et attendez d'autant avant de réessayer.
- Étalez les requêtes dans le temps au lieu de toutes les envoyer d'un coup.
- Déplacez les tâches à fort volume et non interactives vers le traitement par lots.
- Routez les étapes à fort volume vers un modèle moins cher — voir Choisir un modèle.
Voir Choisir un modèle pour sélectionner le bon modèle pour les étapes à fort volume.
Migration de modèle
Les identifiants de modèle sont datés/versionnés et finissent dépréciés. Isolez-vous :
- Lisez l'identifiant de modèle depuis la configuration, pas depuis des littéraux disséminés.
- Surveillez les dépréciations — voir Veille dépréciations & migration et la table des modèles.
- Relancez vos évaluations quand vous changez de modèle.
- 400/401/403 sont de votre fait — corrigez la requête ou les identifiants, ne réessayez pas à l'aveugle. 429 et 500/529 sont réessayables.
- Réessayez les erreurs transitoires avec un backoff exponentiel + jitter, plafonné (p. ex. min(2 ** attempt + random(), 30)).
- Sur un 429 : respectez retry-after, lissez les pics, traitez le travail hors ligne par lots, et routez les étapes à fort volume vers un modèle moins cher.
- Lisez les identifiants de modèle depuis la configuration, surveillez les dépréciations, et relancez les évaluations lors d'une migration de modèle.