Leçon 3 sur 4 · 8 minutes

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.

StatutCode courantQue faire
400validation_error, model_requiredCorrigez la requête. error.param nomme le champ.
401unauthorisedVérifiez la clé et l’en-tête Authorization.
402insufficient_fundsAjoutez des crédits, ou utilisez phaseo/free.
403guardrail_blockedModifiez la requête ou le garde-fou.
404not_foundVérifiez le chemin et l’ID.
410model_retiredPassez à replacement_model.
429rate_limit_exceeded, key_limit_exceededAttendez Retry-After, puis relancez.
5xxupstream_error, gateway_errorRelancez 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é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

Orientez votre code selon 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

La progression est enregistrée dans ce navigateur.

Dernière vérification le 17 novembre 2026