Quand une requête échoue
Orientez votre code selon le code d’erreur et le statut, et ne relancez que les erreurs qui peuvent réussir plus tard.
Chaque erreur Phaseo a le même corps JSON sur tous les endpoints. L’objet error a la forme que les SDK compatibles OpenAI lisent déjà :
{
"error": {
"code": "insufficient_funds",
"message": "...",
"type": "insufficient_quota",
"param": null
},
"generation_id": "G-...",
"status_code": 402
}
Orientez votre code selon error.code et le statut HTTP, jamais selon le texte du message. Journalisez toujours generation_id.
| Statut | Code courant | Que faire |
|---|---|---|
400 | validation_error, model_required | Corrigez la requête. error.param nomme le champ. |
401 | unauthorised | Vérifiez la clé et l’en-tête Authorization. |
402 | insufficient_funds | Ajoutez des crédits, ou utilisez phaseo/free. |
403 | guardrail_blocked | Modifiez la requête ou le garde-fou. |
404 | not_found | Vérifiez le chemin et l’ID. |
410 | model_retired | Passez à replacement_model. |
429 | rate_limit_exceeded, key_limit_exceeded | Attendez Retry-After, puis relancez. |
5xx | upstream_error, gateway_error | Relancez avec un délai croissant. |
Ne relancez pas telles quelles les erreurs 4xx autres que 429 : elles échoueront de nouveau. Pour 429, attendez Retry-After (en secondes ou sous forme de date HTTP), ou utilisez un délai exponentiel avec une part d’aléatoire. Un key_limit_exceeded sans Retry-After ne se réinitialise pas tout seul : ne le relancez pas. Ne relancez les 5xx que si répéter l’appel est sans risque, et fixez un nombre maximal de tentatives et une échéance globale.
Vérifiez votre compréhension
Votre requête renvoie 401 avec le code unauthorised. Que doit faire votre code ?
Mettez-le en pratique
Un script de traitement par lots envoie 500 requêtes dans une boucle. À mi-parcours, les réponses reviennent en 429 avec un en-tête Retry-After: 20. Que changez-vous ?
Afficher la réponseMasquer la réponse
Faites respecter Retry-After par le script : faites une pause d’environ 20 secondes avant de relancer, et utilisez un délai exponentiel avec une part d’aléatoire quand l’en-tête manque. Vérifiez aussi error.code : rate_limit_exceeded se réinitialisera, mais un key_limit_exceeded sans Retry-After non, donc le relancer ne sert à rien.
À retenir
error.code et le statut, corrigez les erreurs 4xx, et ne relancez que les 429 et les 5xx sans risque, avec un délai croissant.Liens utiles
Dernière vérification le 17 novembre 2026