Codes d'erreur et dépannage

Causes et solutions lors de l'appel à 1折AI avec des erreurs 401, 404, 429, 529, 5xx, des délais d'attente et des erreurs Claude Code.

Parcourez d’abord la liste ci-dessous dans l’ordre, la plupart des problèmes se trouvent dans les trois premières étapes.

Ordre de dépannage

Adresse : pour les outils de type Anthropic, renseignez https://1zheai.com ; pour ceux de type OpenAI, renseignez https://1zheai.com/v1. Voir Base URL et authentification.
Clé API (API key) : est-elle complète (sans espaces ou retours à la ligne supplémentaires), a-t-elle été supprimée, est-elle saisie dans le bon champ ?
Solde : le solde dans la console est-il suffisant ?
ID de modèle : est-il exactement identique à celui des modèles pris en charge ?
Réseau : désactivez le proxy et réessayez en connexion directe.
Toujours pas : fournissez une reproduction curl minimale (voir ci-dessous) avec la réponse et le délai.

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i affiche également les codes de statut et les en-têtes de réponse, ce qui est très utile pour le dépannage.

Table de référence des codes d’erreur

Code de statut	Cause courante	Que faire
400	Problème dans le corps de la requête : nom de paramètre incorrect, type de champ incorrect, `max_tokens` dépasse la limite du modèle, champ beta non reconnu par l’amont	Vérifiez le champ indiqué dans `message` ; pour Claude Code, voir « Extra inputs are not permitted » ci-dessous
401	Clé API invalide, supprimée, désactivée, expirée, quota personnel épuisé, ou absente/mal placée dans l’en-tête	Toutes les réponses sont `Invalid token`, vérifiez chaque point ; pour Anthropic natif, utilisez `x-api-key` ou `Authorization: Bearer`
403	Solde du compte insuffisant (`billing_error` / `insufficient_quota`) ; cette clé API n’a pas accès à ce modèle ; l’IP de la requête n’est pas dans la liste blanche de cette clé API (tous `permission_error`)	Rechargez, ou modifiez les restrictions de modèle et la liste blanche IP de cette clé API sur la page « Clés API »
404	Chemin incorrect, ou modèle inexistant / actuellement indisponible	Vérifiez l’adresse avec `Invalid URL` ; vérifiez l’ID de modèle et la liste disponible avec `not_found_error` / `model_not_found`
413	Corps de requête trop volumineux	Réduisez le contenu envoyé en une fois, divisez les gros fichiers
429	Limitation temporaire de débit côté amont. Actuellement, nous n’appliquons pas de limite de débit aux clés API	Réessayez plus tard, ajoutez un backoff exponentiel aux tâches par lot
503	Le modèle existe mais aucun service amont sain n’est disponible pour l’instant, ou panne temporaire du service	Réessayez plus tard ; en cas d’échec persistant, contactez le support avec l’ID de requête
500 / 502	Panne temporaire de la passerelle ou de l’amont	Réessayez plus tard ; si cela persiste, envoyez un e-mail à [email protected]
504	Délai d’attente de la requête dépassé	Utilisez le streaming pour les sorties longues ; augmentez le délai d’attente du client
529	Surcharge de l’amont Anthropic (`overloaded_error`)	Attendez quelques secondes et réessayez, ou changez temporairement de modèle

Le sens complet des types d’erreur officiels Anthropic (invalid_request_error, authentication_error, rate_limit_error, overloaded_error, etc.) est documenté dans la documentation officielle Errors.

Les erreurs renvoyées par l’amont sont transmises telles quelles avec leur code de statut et message, et message ajoute en fin le request id de cette requête. Lors du passage par /v1/messages, la structure externe est la structure officielle {"type":"error","error":{...}}, error.type est rempli avec le type officiel selon le code de statut ; lors du passage par /v1/chat/completions, il s’agit de la structure OpenAI {"error":{...}}.

Réponses réelles testées

Voici les réponses réelles obtenues lors d’un test le 2026-10-15 sur /v1/messages. Lors du passage par /v1/chat/completions, le contenu est identique, sans "type":"error" à l’extérieur, et error contient en plus un champ code.

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

L’explication du 404 lorsque le modèle est inexistant ou indisponible est donnée dans modèles pris en charge. Le request id dans la réponse correspond à cette requête précise ; joignez-le lors d’un signalement de problème.

Dépannage par symptôme

401 / Invalid token

La clé API a été copiée avec des espaces ou retours à la ligne supplémentaires ; recopiez-la.
La clé API a été supprimée ou désactivée dans la console, ou elle a expiré / son quota est épuisé. Dans tous ces cas, la réponse est la même phrase Invalid token.
Dans Claude Code, ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN sont tous deux définis, et l’un des deux est une ancienne valeur : ne gardez qu’un seul, ANTHROPIC_AUTH_TOKEN est recommandé.
env de settings.json écrase la variable du même nom exportée dans le terminal ; si la modification de la variable du terminal n’a aucun effet, vérifiez ~/.claude/settings.json.

404 / Invalid URL

Vérifiez d’abord le type d’erreur : not_found_error ou model_not_found nécessitent de vérifier l’ID de modèle et la liste disponible. Pour Invalid URL, vérifiez /v1 : OpenAI SDK, Cursor, Cline (OpenAI Compatible) doivent être renseignés dans https://1zheai.com/v1 ; Claude Code et l’SDK Anthropic ne renseignent que https://1zheai.com, renseigner /v1 donnera /v1/v1/messages.

403 / error code: 1010

Si la réponse ne contient que la ligne error code: 1010 sans JSON, la requête a été bloquée avant d’atteindre la passerelle. On sait actuellement que cela se produit avec les requêtes envoyées directement via la bibliothèque standard Python urllib (son User-Agent par défaut est Python-urllib/3.x). Ajoutez votre propre User-Agent dans les en-têtes, ou utilisez l’SDK officiel, requests, httpx.

429 Trop de requêtes

Actuellement, aucune limite de débit n’est appliquée aux clés API. La réception d’un 429 est généralement due à une charge élevée côté amont ; réessayez plus tard. Pour les tâches par lot, ajoutez un backoff exponentiel : après un échec, attendez un certain temps avant de réessayer, doublez la durée d’attente à chaque fois, et contrôlez la concurrence avec votre propre file d’attente.

529 / overloaded_error

L’amont Anthropic est temporairement en surcharge, sans rapport avec votre clé API ou votre solde. Attendez quelques secondes et réessayez ; si vous êtes pressé, changez temporairement pour un autre modèle de la même série.

Délais d’attente, interruption en cours de streaming

Pour les réponses longues, utilisez autant que possible le streaming ("stream": true), moins susceptible d’être coupé par les équipements réseau intermédiaires.
Claude Code permet d’augmenter le délai d’attente avec API_TIMEOUT_MS, par défaut 600000 (10 minutes).
Si un proxy est actif, désactivez-le d’abord et réessayez ; de nombreuses interruptions de flux proviennent des nœuds de proxy.

Claude Code : ouverture directe de l’écran de connexion

Cela signifie que Claude Code n’a pas lu votre clé API. Exécutez /status dans Claude Code et vérifiez les lignes base URL et source des identifiants ; si elles sont vides, retournez à Claude Code integration pour vérifier les variables d’environnement ou settings.json.

Claude Code : Extra inputs are not permitted / context_management renvoie 400

Claude Code inclut certains champs beta expérimentaux dans les requêtes ; un amont strict qui ne les reconnaît pas renverra 400. Définissez la variable d’environnement suivante pour les désactiver (issue de la documentation officielle LLM gateway de Claude Code) :

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Solde suffisant mais échec de l’appel

Si seul un modèle échoue, il est peut-être temporairement indisponible, son ID est mal écrit, ou cette clé API a une restriction de modèle (403 This token has no access to model …).
Si tout échoue avec un 401, vérifiez si cette clé API a un plafond de quota déjà atteint, ou si elle a expiré. Cela est visible dans les colonnes « Quota ($) » et « Expiration » de la page « Clés API ».
Pour les autres cas, consultez le tableau des codes d’erreur ci-dessus.

Limitation des tentatives et modèle de retour

N’utilisez pas de boucle infinie pour masquer des erreurs de configuration. Pour les délais d’attente du SDK, le nombre de tentatives automatiques et le backoff, voir Délais d’attente et tentatives.

Lorsque vous contactez le support, vous pouvez copier le modèle suivant, supprimer les clés, les en-têtes d’authentification et le contenu privé avant l’envoi :

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

Toujours pas résolu

Envoyez un e-mail à [email protected] avec l’heure, l’ID de modèle, l’outil et la version utilisés, et la sortie complète de curl -i (sans la clé API).