Erreurs, limites de débit et fiabilité
Le code de production communique avec un service réseau ; il doit donc s'attendre à des défaillances. Un peu de structure ici fait toute la différence entre une intégration instable et une intégration fiable.
La carte des erreurs
Statuts HTTP typiques que vous aurez à gérer :
| Statut | Signification | Que faire |
|---|---|---|
| 400 | Requête invalide | Corrigez la charge utile ; ne réessayez pas en l'état |
| 401 | Clé API erronée/manquante | Vérifiez les identifiants |
| 403 | Non autorisé | Vérifiez l'accès/les permissions |
| 429 | Débit limité | Patientez et réessayez (respectez retry-after) |
| 500/529 | Erreur serveur / surcharge | Réessayez avec backoff |
Les SDK exposent ces cas sous forme d'exceptions typées, vous permettant de brancher proprement au lieu d'analyser des chaînes.
Nouvelles tentatives avec backoff
Pour les erreurs transitoires (429, 5xx), réessayez avec un backoff exponentiel + gigue, 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.)
Limites de débit
Les limites s'appliquent par compte/palier (requêtes et tokens par minute). Lorsque vous en atteignez une, vous recevez un 429 avec des indications de timing. Stratégies : respectez retry-after, lissez les pics, traitez par lots le travail hors ligne, et utilisez un modèle moins cher (Choisir un modèle) pour les étapes à fort volume.
Migration de modèle
Les identifiants de modèles sont datés/versionnés et finissent par être dépréciés. Protégez-vous :
- Lisez l'identifiant de modèle depuis la configuration, et non depuis des littéraux éparpillés.
- Surveillez les dépréciations — voir Veille dépréciation et migration et le tableau des modèles.
- Réexécutez vos évaluations lorsque vous changez de modèle.