Erreurs et limites de débit de l'API OpenAI : 401, 404, 429, 5xx (2026)

Les erreurs de l'API OpenAI semblent très variées, mais il suffit de distinguer cinq niveaux : la requête est-elle partie, l'identité est-elle correcte, l'adresse et le modèle sont-ils bons, les paramètres sont-ils valides, et le quota ou la limite de débit est-il atteint. En suivant un ordre fixe, la plupart des problèmes se localisent en quelques minutes.

Cet article détaille les codes 401, 403, 404, 400, 429 et 5xx, avec des commandes de reproduction minimale, une stratégie de nouvelle tentative et un ordre de diagnostic constant. Les noms de modèles et la configuration de la passerelle sont ceux de la page Tarifs des modèles et de la documentation d'intégration.

Remarque : OpenAI, GPT et ChatGPT sont des marques de leurs détenteurs respectifs. Cet article décrit le comportement courant des interfaces en octobre 2026 ; les codes d'erreur et règles de limite suivent la documentation officielle et les réponses réelles.

1. Conserver trois preuves

Avant de diagnostiquer, sauvegardez ces trois éléments :

le code de statut HTTP ;
les champs error.type, error.code et error.message du corps de réponse ;
l'en-tête x-request-id.

L'identifiant de requête est l'information la plus utile pour dialoguer avec le fournisseur. Sans lui, vous ne pouvez décrire qu'un « échec vers telle heure » ; avec lui, le fournisseur retrouve la requête, l'amont et la facturation exacts.

Code	Type courant	Première hypothèse
400	`invalid_request_error`	Paramètre, JSON ou longueur de contexte incorrect
401	`authentication_error`	Clé absente, erronée ou invalide
403	`permission_error`	La clé n'a pas accès à ce modèle ou projet
404	`not_found_error`	URL de base ou nom de modèle incorrect
429	`rate_limit_error` / `insufficient_quota`	Limitation de débit ou solde insuffisant
500/502/503/504	`server_error`	Panne amont ou coupure réseau

2. 401 et 403 : identité et permissions

Un 401 signifie que le serveur ne reconnaît pas la clé. Causes fréquentes :

en-tête Authorization: Bearer absent ;
espace, retour à la ligne ou troncature lors de la copie de la clé ;
clé supprimée, renouvelée ou projet associé désactivé ;
clé de passerelle envoyée à l'adresse officielle, ou clé officielle envoyée à la passerelle ;
faute de frappe dans la variable d'environnement, qui envoie en réalité une chaîne vide.

Un 403 signifie plutôt « je vous reconnais, mais je ne vous autorise pas ». Par exemple, la clé n'a pas les droits sur le modèle, l'organisation est restreinte ou le projet n'a pas activé la capacité demandée. Face à un 403, ne réessayez pas en boucle : vérifiez le projet de la clé et les permissions du modèle dans la console.

Auto-vérification rapide :

curl -sS "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Si la liste des modèles s'affiche, la clé et l'adresse sont globalement correctes. Si un 401 persiste, examinez d'abord la clé elle-même et la variable d'environnement.

3. 404 : adresse ou modèle inexistant

Un 404 ne signifie pas nécessairement que l'interface a été retirée ; le plus souvent, le chemin est mal écrit. Cas courants :

Symptôme	Cause	Traitement
`404 page not found`	URL de base avec un `/v1` en trop ou manquant	Écrire uniformément `https://api.zhongshangqihang.com/v1`
`model_not_found`	Nom de modèle mal orthographié ou non activé	Copier le nom depuis la page Tarifs des modèles
404 avec double barre oblique	Un `/` en trop lors de la concaténation	Supprimer la barre en double
404 signalé par le SDK	`base_url` et chemin d'interface dupliqués	Ne conserver qu'un seul `/v1`

Commencez par une requête minimale en curl pour écarter un problème de concaténation du SDK. Si curl fonctionne et le SDK échoue, le problème vient généralement du base_url, du proxy ou de la version du SDK.

4. 400 : paramètres et contexte

Un 400 indique que la requête elle-même est invalide ; réessayer ne sert à rien. Causes fréquentes :

JSON mal formé : virgule finale, guillemets simples, retour à la ligne non échappé ;
paramètre non pris en charge par le modèle, par exemple certains paramètres d'échantillonnage ;
max_tokens supérieur à la limite du modèle ;
entrée dépassant la fenêtre de contexte, avec context_length_exceeded ;
format, taille ou URL d'image inaccessible ;
schéma d'outil invalide, champ obligatoire manquant.

La méthode : réduire à la requête minimale, puis rajouter les paramètres un par un. Ne modifiez pas cinq éléments à la fois, sinon la disparition de l'erreur ne dit pas lequel était en cause.

5. 429 : limitation de débit ou solde insuffisant

Le 429 est le code le plus souvent mal interprété. Il a au moins deux significations :

Code d'erreur	Signification	Traitement
`rate_limit_exceeded`	Fréquence, débit de jetons ou concurrence dépassés	Réduire la concurrence, mettre en file, délai exponentiel
`insufficient_quota`	Solde insuffisant ou quota épuisé	Recharger, changer de clé, vérifier le quota du projet

Lisez d'abord le corps et les en-têtes. retry-after indique le délai conseillé ; x-ratelimit-remaining-requests et x-ratelimit-remaining-tokens indiquent le quota restant. Si le restant est à zéro, attendre ne servira à rien : il faut attendre la réinitialisation de la fenêtre ou augmenter la limite.

Une logique de nouvelle tentative utilisable :

import random
import time
from openai import OpenAI

client = OpenAI(
    api_key="sk-votre-clé",
    base_url="https://api.zhongshangqihang.com/v1",
)

def chat(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="gpt-5.5",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=500,
                timeout=60,
            )
            return resp.choices[0].message.content
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status not in (429, 500, 502, 503, 504) or attempt == retries - 1:
                raise
            wait = min(2 ** attempt, 16) + random.random()
            print(f"{status}, nouvelle tentative dans {wait:.1f} s : {exc}")
            time.sleep(wait)
    raise RuntimeError("unreachable")

Les nouvelles tentatives ne sont utiles que pour 429, 5xx et les erreurs réseau. Réessayer un 400, 401, 403 ou 404 ne fait que consommer du temps et du quota.

6. 5xx : panne amont et réseau

500, 502, 503 et 504 ne viennent généralement pas d'une requête mal écrite, mais d'un service amont anormal, d'un délai dépassé à la passerelle ou d'une coupure réseau. Principes :

Réessayer une à deux fois avec délai exponentiel et gigue aléatoire.
Pour le streaming, déterminer si du contenu a déjà été reçu : une sortie partielle peut avoir été facturée.
Les opérations idempotentes peuvent être réessayées automatiquement ; les autres exigent une clé de déduplication.
En cas de 5xx massifs, consulter la page d'état du fournisseur plutôt que d'augmenter la concurrence.
Conserver l'identifiant de requête pour aider le fournisseur à localiser l'incident.

Si seules vos requêtes renvoient des 5xx alors que d'autres équipes fonctionnent, vérifiez en priorité la taille du corps, les délais d'attente et la chaîne de proxy.

7. Un ordre de diagnostic fixe

Face à une erreur, suivez cet ordre sans sauter d'étape :

Envoyer une requête minimale en curl pour confirmer l'adresse et la clé.
Comparer adresse officielle et adresse de passerelle, et vérifier qu'aucune clé n'est mélangée.
Vérifier que l'URL de base ne contient qu'un seul /v1.
Vérifier que le nom du modèle vient de la page de tarifs et qu'il est activé.
Supprimer les paramètres optionnels et confirmer que la requête minimale passe.
Vérifier le solde, le quota du projet et le plafond de la clé.
Lire les en-têtes du 429 pour distinguer limitation et solde.
Consulter la page d'état du fournisseur pour écarter une panne amont.
Sauvegarder identifiant, code et corps de réponse avant de contacter le support.

8. Questions fréquentes

Un 429 signifie-t-il toujours un appel trop rapide ?

Non. Un 429 peut venir d'un dépassement de fréquence ou de concurrence, ou d'un solde insuffisant. Lisez error.code et les en-têtes ; ne réduisez pas systématiquement la vitesse.

Suffit-il de changer de clé pour corriger un 401 ?

Changer de clé écarte un problème de clé, mais pas une adresse mélangée, une variable vide ou un projet sans permission. Vérifiez d'abord où la requête est réellement envoyée.

Un 404 signifie-t-il que le modèle est retiré ?

Le plus souvent, l'URL de base ou le nom du modèle est incorrect. Appelez /v1/models en curl, puis comparez le nom avec la page de tarifs.

Peut-on réessayer indéfiniment un 5xx ?

Non. Fixez un nombre maximal de tentatives et un délai total pour éviter l'accumulation de requêtes pendant la panne. En streaming, tenez compte du fait qu'une sortie partielle peut déjà être facturée.

Comment distinguer une erreur de passerelle d'une erreur officielle ?

Comparez le format du corps et l'identifiant de requête, puis interrogez l'adresse officielle et celle de la passerelle avec la même clé et le même modèle. La couche qui reproduit l'erreur de façon stable est la source du problème.

Et ensuite

Mettez en place la requête minimale, la journalisation d'usage et la stratégie de nouvelle tentative avant d'envoyer le trafic métier. Si vous avez besoin d'une recharge en yuan et d'une entrée multi-modèles unifiée, vous pouvez créer un compte ZSQH AI Gateway ; les noms de modèles et les prix sont indiqués sur la page Tarifs des modèles.