Gestion des erreurs et codes HTTP
Pe această pagină
Mise à jour du 3 novembre 2026 basée sur la documentation OpenAI :
temperatureettop_pne sont acceptés qu’avec un effort de raisonnement denone, tandis que les modèles GPT-5.6 raisonnent par défaut (medium). Les appels définissant ces paramètres doivent donc spécifierreasoning={"effort": "none"}(API Responses) oureasoning_effort="none"(Chat Completions). Sources : Utilisation de GPT-6 · GPT-5.6 Terra.
Clarification du 3 novembre 2026 basée sur la page Dépréciations d’OpenAI : l’exemple de modèle supprimé utilisait précédemment
gpt-4o, qui reste disponible jusqu’au 14 janvier 2027 ; il utilise désormaisgpt-4-turbo, qui a été arrêté le 23 octobre 2026 (remplacement indiqué :gpt-5.6-sol). Source : Dépréciations.
Gestion des erreurs et codes HTTP
En production, les erreurs sont inévitables. Le réseau tombe, une clé API expire, un collègue déploie un paramètre invalide ou l’API elle-même subit une panne de trois minutes. Comprendre les codes HTTP renvoyés par l’API et les gérer correctement est essentiel pour construire des applications robustes. Tout l’enjeu se résume à une question que vous devez vous poser pour chaque exception : ce problème disparaîtra-t-il si je réessaie, ou vais-je boucler indéfiniment sur un problème qu seul un humain peut résoudre ?
Codes HTTP de l’API OpenAI
L’API renvoie des codes HTTP standards pour indiquer le résultat de chaque requête. Le SDK Python ne vous permet pas de gérer ces codes manuellement ; il traduit plutôt chacun d’eux en une exception typée que vous pouvez intercepter séparément. Cela vous permet d’écrire des blocs except précis plutôt qu’un except Exception fourre-tout qui obscurcirait la nature du problème.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Un code 401 indique que la clé API est invalide ou manquante. Vous rencontrez généralement cette erreur lors du premier déploiement, lorsque la variable d’environnement n’a pas été propagée au conteneur. Réessayer est inutile : la clé sera tout aussi invalide dans dix secondes.
try:
# Clé API invalide ou manquante
bad_client = OpenAI(api_key="sk-invalid")
bad_client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except AuthenticationError as e:
print(f"Code: {e.status_code}") # 401
print(f"Message: {e.message}")
# Action : vérifier la clé API, la régénérer si nécessaire
400 — BadRequestError
Un code 400 vous indique que la requête est mal formée. Ici, une température de 5,0 est fournie alors que la valeur maximale acceptée est 2,0. Le message d’erreur nomme presque toujours le paramètre fautif, ce qui fait de cette erreur la plus rapide à corriger, à condition de la journaliser correctement plutôt que de l’avaler silencieusement.
try:
# Paramètres invalides
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature nécessite effort none
input="Test",
temperature=5.0 # Valeur invalide (max 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Action : corriger les paramètres de la requête
429 — RateLimitError
Un code 429 indique que vous envoyez trop de requêtes ou que vous avez dépassé votre quota. Contrairement aux deux précédentes, cette erreur est temporaire par nature : le compteur se réinitialise. C’est le cas d’école pour une nouvelle tentative, mais une tentative qui attend — et attend plus longtemps à chaque essai.
try:
# Trop de requêtes ou quota dépassé
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except RateLimitError as e:
print(f"Code: {e.status_code}") # 429
print(f"Message: {e.message}")
# Action : attendre et réessayer avec un backoff exponentiel
500/503 — InternalServerError
Les erreurs 500 et 503 proviennent d’OpenAI, pas de vous. Votre requête était valide ; l’infrastructure n’a simplement pas pu la traiter. Réessayez après un délai : dans la grande majorité des cas, la deuxième ou la troisième tentative réussit.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 ou 503
print(f"Message: {e.message}")
# Action : réessayer après un délai ; l'erreur vient du côté d'OpenAI
Gestionnaire d’erreurs complet
Regroupons ces comportements dans une seule fonction. La logique est un triage : les erreurs fatales sont converties en RuntimeError et levées immédiatement, les erreurs transitoires déclenchent une attente qui double à chaque tour, et si le budget de tentatives est épuisé, l’appel échoue proprement plutôt que de renvoyer une valeur vide que l’appelant pourrait mal interpréter.
from openai import OpenAI, APIError, AuthenticationError, RateLimitError
from openai import BadRequestError, APIConnectionError, InternalServerError
import time
client = OpenAI()
def robust_api_call(prompt: str, model: str = "gpt-5.6-terra",
max_retries: int = 3) -> str:
"""Appel API avec gestion complète des erreurs."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Ne pas réessayer — la clé est invalide
raise RuntimeError("Clé API invalide. Vérifiez OPENAI_API_KEY.")
except BadRequestError as e:
# Ne pas réessayer — la requête est mal formée
raise RuntimeError(f"Requête invalide : {e.message}")
except RateLimitError:
# Réessayer avec backoff exponentiel
delay = 2 ** attempt
print(f"Limite de débit atteinte. Attente de {delay}s...")
time.sleep(delay)
except InternalServerError:
# Réessayer — erreur côté serveur
delay = 2 ** attempt
print(f"Erreur serveur. Tentative {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Réessayer — problème réseau
delay = 2 ** attempt
print(f"Erreur de connexion. Tentative {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Échec après {max_retries} tentatives")
# Utilisation
try:
result = robust_api_call("Bonjour !")
print(result)
except RuntimeError as e:
print(f"Erreur fatale : {e}")
Erreurs spécifiques à l’API Responses
Deux situations méritent un traitement séparé car elles apparaissent sous un code générique mais appellent une correction très spécifique.
Contexte trop long
Une invite qui dépasse la fenêtre de contexte renvoie un 400, tout comme une faute de frappe dans un paramètre. Pour distinguer les deux, inspectez le message : la présence de context_length_exceeded vous oriente vers la troncature du texte ou le changement vers un modèle avec une fenêtre de contexte plus grande, plutôt que vers la révision de vos paramètres.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Dépasse la fenêtre de contexte
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("L'invite est trop longue pour ce modèle.")
print("Solutions : tronquer le texte, ou passer à un modèle")
print("avec une fenêtre de contexte plus grande.")
Modèle indisponible
Les identifiants de modèles ne sont pas éternels. Un déploiement qui référence encore un modèle retiré échoue avec un 404, faisant planter toute l’application alors qu’elle fonctionnait la veille. Gérez ce cas explicitement : c’est un rappel automatique pour mettre à jour votre configuration.
try:
response = client.responses.create(
model="gpt-4-turbo", # retiré de l'API le 23 octobre 2026
input="Test"
)
except NotFoundError as e:
print(f"Modèle introuvable : {e.message}")
print("Utilisez gpt-5.6-sol, le remplacement indiqué par OpenAI, ou un modèle plus récent.")
Journalisation structurée des erreurs
Une erreur non journalisée est une erreur que vous découvrirez via un ticket client. La journalisation en JSON plutôt qu’en texte libre change tout lorsque vous devez agréger : vous pouvez compter les 429 par heure, filtrer par response_id ou suivre la dérive de la consommation, ce qui est impossible avec des lignes de log écrites à la main.
import logging
import json
from datetime import datetime
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("openai_client")
def call_with_log(prompt: str) -> str:
"""Appel API avec journalisation structurée."""
request_id = None
try:
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
logger.info(json.dumps({
"event": "api_success",
"model": response.model,
"tokens": response.usage.total_tokens,
"response_id": response.id,
"timestamp": datetime.now().isoformat()
}))
return response.output_text
except APIError as e:
logger.error(json.dumps({
"event": "api_error",
"status_code": e.status_code,
"message": e.message,
"timestamp": datetime.now().isoformat()
}))
raise
result = call_with_log("Bonjour !")
Tableau récapitulatif
Gardez cette grille à portée de main : elle résume la décision à prendre pour chaque code.
| Code | Exception | Réessayer ? | Action |
|---|---|---|---|
| 400 | BadRequestError | Non | Corriger la requête |
| 401 | AuthenticationError | Non | Vérifier la clé API |
| 403 | PermissionDeniedError | Non | Vérifier les permissions |
| 404 | NotFoundError | Non | Vérifier le modèle/le point de terminaison |
| 422 | UnprocessableEntityError | Non | Corriger le format |
| 429 | RateLimitError | Oui | Backoff exponentiel |
| 500 | InternalServerError | Oui | Attendre et réessayer |
| 503 | InternalServerError | Oui | Service temporairement indisponible |
Puncte cheie
- Catégorisez les erreurs : réessayables (429, 500, 503) vs fatales (400, 401, 403)
- Utilisez un backoff exponentiel pour les erreurs réessayables
- Ne réessayez jamais les erreurs d’authentification ou de requête invalide
- Journalisez chaque erreur avec son contexte (code, message, horodatage)
- Le SDK gère automatiquement 2 nouvelles tentatives — configurez
max_retriessi nécessaire