Erreurs de l'API GPT-6 Astra : 15 problèmes courants et comment les résoudre
Diagnostiquer 15 pannes courantes de l'API GPT-6 Astra, y compris les erreurs 400, 401, 403, 404, 409, 422, 429, 500, 503, les dépassements de délai, l'état WebSocket, les outils et le streaming.
La façon la plus rapide d'aggraver un incident API est de réessayer chaque erreur. Un schéma malformé ne se réparera pas avec un backoff, et un solde de crédits épuisé ne se rétablira pas parce qu'un worker a essayé dix fois de plus. Diagnostiquez les erreurs par statut HTTP, classe SDK, error.type, et surtout error.code.
Un gestionnaire d'erreurs sécurisé
SORTIE UNIQUEMENT TRADUCTION :
try {
return await client.responses.create({
model: "gpt-6-astra",
entrée
});
} catch (error) {
si (error instanceof OpenAI.APIConnectionError) {
// Network, proxy, TLS, DNS or firewall path.
} else if (error instanceof OpenAI.RateLimitError) {
// Inspect code and Retry-After before deciding to retry.
} else if (error instanceof OpenAI.APIError) {
console.error(error.status, error.message, error.code);
} sinon {
lancer une erreur ;
}
}
Enregistrez l'ID de la requête, l'horodatage et le fuseau horaire, le modèle, le point de terminaison, le statut, le code, le nombre de tentatives et les caractéristiques de la charge utile nettoyée. Ne journalisez jamais les clés API ou le contenu confidentiel des invites par défaut.
1. 400 Requête Incorrecte
La charge utile est mal formée ou incompatible : champ erroné, entrée manquante, schéma d'outil invalide, combinaison non prise en charge ou contenu mal encodé. Lisez le message, comparez-le avec la référence actuelle des réponses et ajoutez des tests de contrat. Ne réessayez pas avec une entrée inchangée.
2. Erreur d'authentification 401
La clé ou le jeton est invalide, expiré, révoqué ou envoyé incorrectement. Confirmez l'injection du secret et l'environnement du projet. Faites pivoter les clés exposées ; ne les imprimez jamais lors du débogage.
3. 401 Organisation ou projet incorrect
Une clé valide peut toujours cibler le mauvais périmètre. Vérifiez la configuration du projet et tout en-tête explicite d'organisation/projet. Alignez la clé, la ressource et le périmètre de facturation.
4. 401 IP non autorisé
La source de la requête ne correspond pas à la liste d'autorisation configurée. Envoyez depuis une adresse IP de sortie approuvée ou mettez à jour la liste d'autorisation via une administration autorisée. Réessayer depuis la même source ne sert à rien.
5. 403 Permission refusée ou région non prise en charge
L'appelant n'a pas accès à la ressource, au modèle ou à la région. Vérifiez le rôle du projet, la disponibilité du modèle, la propriété de la ressource et les règles relatives aux pays pris en charge. Ne déguisez pas un problème d'autorisation en « introuvable » dans les journaux internes.
6. 404 Non Trouvé
Un identifiant de réponse, de conversation, de magasin vectoriel, de fichier ou autre est incorrect, expiré ou inaccessible. Vérifiez l'ID exact et le projet. Si destiné à l'utilisateur, évitez de divulguer l'existence de ressources en dehors du périmètre de cet utilisateur.
7. 409 Conflit
Une autre requête a modifié la ressource simultanément. Rechargez l'état actuel, réappliquez la modification souhaitée sur la nouvelle version et utilisez le verrouillage optimiste ou l'idempotence. Les tentatives immédiates et aveugles peuvent répéter le conflit.
8. 422 Entité non traitable
Le format est syntaxiquement acceptable mais le service ne peut pas le traiter. Validez les tailles, les encodages, l'état du fichier et les combinaisons de champs. Le tableau officiel suggère de réessayer, mais commencez par éliminer les causes déterministes.
9. Limite de taux de requêtes ou de jetons 429
Rythmez le trafic et respectez Retry-After lorsqu'il est présent. Sinon, utilisez un backoff exponentiel borné avec gigue. Coordonnez les budgets de réessai entre les travailleurs afin qu'ils ne créent pas un effet de troupeau tonitruant. Réduisez les appels redondants et les rafales de jetons importantes.
10. 429 ralentir
Ceci est un signal de limitation de débit : le trafic a augmenté trop rapidement, même si les limites principales semblent suffisantes. Suivez Retry-After, réduisez le taux de requêtes, puis augmentez progressivement. Les recommandations actuelles d'OpenAI donnent une règle empirique selon laquelle, après avoir atteint un million de jetons d'entrée par minute, la croissance ne doit pas dépasser 50 % toutes les 15 minutes ; l'activation réelle varie selon le modèle et les conditions.
11. Limite de crédit, de dépense ou d'utilisation 429
Les codes incluent credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded et organization_usage_limit_exceeded. Ceux-ci nécessitent des crédits ou des modifications de limites. Réessayer ne peut pas restaurer l'accès. Alertez un propriétaire et échouez rapidement.
12. 500 Erreur Interne du Serveur
Réessayez après une brève attente avec un budget limité et vérifiez la page d'état si les échecs persistent. Capturez l'ID de la requête pour le support. Pour un workflow modifiant l'état, réconciliez les effets secondaires des outils avant de rejouer l'ensemble de la requête.
13. 503 Modèle surchargé
Le type/code documenté est service_unavailable_error / server_is_overloaded. Respectez Retry-After ou reculez en son absence. Notez que les recommandations actuelles du SDK Python distinguent RateLimitError pour 429 de InternalServerError pour 503 ; interceptez les deux si votre logique de surcharge supposait auparavant que tout problème de capacité était un 429.
14. Erreurs de connexion ou de délai d'attente
APIConnectionError peut indiquer des problèmes de réseau, de proxy, de certificat TLS, de DNS ou de pare-feu. APITimeoutError signifie que le délai imparti est écoulé. Réessayez les lectures sûres, inspectez les paramètres du proxy d'entreprise et évitez de désactiver la vérification TLS. Pour les écritures, déterminez si l'opération a eu lieu avant de réessayer.
15. État WebSocket et échecs de streaming
previous_response_not_found signifie que l'état référencé ne peut pas être résolu ; les directives officielles recommandent de renvoyer le contexte d'entrée complet avec previous_response_id défini sur null. websocket_connection_limit_reached reflète la limite de connexion de 60 minutes ; ouvrez une nouvelle connexion et continuez. Gérez également les événements response.failed, response.incomplete et les événements de transport error plutôt que de supposer que la fermeture du socket équivaut à une fin.
Une matrice de réessai
| Classe | Réessayer inchangé ? | Action correcte |
| 400/401/403/404 | Non | Corriger la requête, l'identité, l'autorisation ou l'ID |
| 409 | Après réconciliation | Recharger la version et appliquer de manière sécurisée |
| 422 | Parfois | Vérifier d'abord la cause déterministe |
| 429 rate/slow_down | Oui, limité | Respecter Retry-After ; backoff et jitter |
| 429 facturation/limites | Non | Ajouter des crédits ou modifier les limites approuvées |
| 500/503 | Oui, limité | Recul, vérification du statut, conserver l'ID de la requête |
| Connexion/délai d'attente | Dépend | Relire les lectures ; concilier les écritures |
Tentatives de capacité et temps de nouvelle tentative écoulé total. Utilisez un disjoncteur lors d'incidents étendus et un chemin de lettre morte pour les tâches nécessitant une révision par un opérateur. Les nouvelles tentatives doivent être observables, non cachées dans des boucles empilées de SDK et d'application.
FAQ
Dois-je réessayer à chaque 429 ?
Non. Les erreurs de débit et de rampe peuvent être réessayées après le délai requis ; les erreurs de crédit, de dépense et de limite d'utilisation nécessitent une action sur le compte.
Pourquoi enregistrer l’ID de requête ?
Cela permet au support et à votre propre télémétrie de corréler une défaillance avec une requête API spécifique sans exposer la charge utile complète.
Puis-je réessayer un appel d'outil qui a expiré ?
Uniquement après avoir déterminé s'il a provoqué un effet secondaire. Utilisez des clés d'idempotence et une réconciliation par lecture avant nouvelle tentative.
Que doivent voir les utilisateurs ?
Un message concis et exploitable, avec une option de nouvelle tentative sécurisée le cas échéant. Conservez les traces de pile, les codes fournisseur et les informations sensibles dans les diagnostics protégés.
Conclusion
Une gestion fiable des erreurs de GPT-6 Astra commence par la classification. Corrigez les requêtes 4xx déterministes, distinguez la pression de débit des limites de facturation, reculez face aux échecs transitoires 5xx, réconciliez les écritures incertaines et modélisez le streaming comme une machine d'états. Une politique de tentatives limitées, associée à une bonne télémétrie au niveau des requêtes, résout plus d'incidents que des tentatives aveugles ne le feront jamais.
