Salt la conținutul principal
Română— Alege o limbă
Meniu

Gestion des erreurs et codes HTTP

Lecția 12 din 22 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Gestion des erreurs et codes HTTP
  2. Codes HTTP de l’API OpenAI
  3. Gestionnaire d’erreurs complet
  4. Erreurs spécifiques à l’API Responses
  5. Journalisation structurée des erreurs
  6. Tableau récapitulatif
  7. Puncte cheie

Mise à jour du 3 novembre 2026 basée sur la documentation OpenAI : temperature et top_p ne sont acceptés qu’avec un effort de raisonnement de none, tandis que les modèles GPT-5.6 raisonnent par défaut (medium). Les appels définissant ces paramètres doivent donc spécifier reasoning={"effort": "none"} (API Responses) ou reasoning_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ésormais gpt-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.

CodeExceptionRéessayer ?Action
400BadRequestErrorNonCorriger la requête
401AuthenticationErrorNonVérifier la clé API
403PermissionDeniedErrorNonVérifier les permissions
404NotFoundErrorNonVérifier le modèle/le point de terminaison
422UnprocessableEntityErrorNonCorriger le format
429RateLimitErrorOuiBackoff exponentiel
500InternalServerErrorOuiAttendre et réessayer
503InternalServerErrorOuiService 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_retries si nécessaire