--- title: "Codes d'erreur et dépannage" description: "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." headingIds: {"Ordre de dépannage":"section-1","Table de référence des codes d’erreur":"section-2","Réponses réelles testées":"section-3","Dépannage par symptôme":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 Trop de requêtes":"section-8","529 / overloaded_error":"section-9","Délais d’attente, interruption en cours de streaming":"section-10","Claude Code : ouverture directe de l’écran de connexion":"section-11","Claude Code : Extra inputs are not permitted / context_management renvoie 400":"section-12","Solde suffisant mais échec de l’appel":"section-13","Limitation des tentatives et modèle de retour":"section-14","Toujours pas résolu":"section-15"} --- 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 1. **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](/fr/docs/base-url/). 2. **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 ? 3. **Solde** : le solde dans la console est-il suffisant ? 4. **ID de modèle** : est-il exactement identique à celui des [modèles pris en charge](/fr/docs/models/) ? 5. **Réseau** : désactivez le proxy et réessayez en connexion directe. 6. **Toujours pas** : fournissez une reproduction curl minimale (voir ci-dessous) avec la réponse et le délai. ```bash title="最小复现" curl -i https://1zheai.com/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -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 à support@1zheai.com | | 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](https://platform.claude.com/docs/en/api/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`. ```json title="401 API 密钥无效、禁用、过期或额度用完" {"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"} ``` ```json title="403 账户余额不足" {"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"} ``` ```json title="403 API 密钥没开通该模型" {"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"} ``` ```json title="403 IP 不在白名单" {"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"} ``` ```json title="400 上游参数错误" {"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"} ``` ```json title="404 路径不存在" {"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](/fr/docs/models/). 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](/fr/docs/models/). 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](/fr/docs/quickstart-claude-code/) 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) : ```bash 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](/fr/docs/retries/). 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 : ```text 发生时间与时区： 客户端及版本： 请求方法与完整路径： 模型 ID： HTTP 状态码： request id（如有）： 脱敏后的错误正文： 最小请求能否复现： 是否使用代理 / 是否仅某个模型失败： ``` ## Toujours pas résolu Envoyez un e-mail à support@1zheai.com 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).