# Codes d'erreur

> Tous les codes d'erreur de l'API YesCaptcha avec leur signification et la marche à suivre : format de la requête, compte et solde, tâches simultanées et suspension, résultat de la tâche, paramètres du site, images, proxy, serveur. Les requêtes qui renvoient une erreur ne sont pas débitées.

Source: https://docs.yescaptcha.com/fr/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

En cas d’échec, l’API renvoie `errorId: 1`, un code d’erreur dans `errorCode` et une description textuelle dans `errorDescription`. Les requêtes qui renvoient une erreur ne sont pas débitées : aucun débit de points si l’erreur survient à la création de la tâche, et remboursement automatique de points si la tâche échoue ou expire après sa création.

> **Astuce:** Dans votre code, testez `errorCode` et non le texte de `errorDescription`, qui peut changer.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## Marche à suivre

1.  **Erreurs de paramètres** (format de la requête, ClientKey, type de tâche, paramètres du site, images) : renvoyer la même requête ne changera rien, corrigez-la d’abord.
2.  **Échecs de reconnaissance et expirations** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) : vous pouvez créer une nouvelle tâche.
3.  Après une erreur, **arrêtez l’interrogation périodique (polling)** de ce `taskId` et ne renvoyez pas la même requête à haute fréquence.
4.  Pour les erreurs marquées « compte pour la suspension automatique », un même `clientKey` qui en accumule 100 en une minute voit la création de tâches suspendue pendant 5 minutes. Les erreurs marquées « en cache » ne comptent pas, mais pendant la durée du cache, la même requête renvoie directement la même erreur. Voir [Limite de tâches simultanées et suspension automatique](https://docs.yescaptcha.com/fr/api/rate-limits.md).

## Tous les codes d’erreur

### Format de la requête

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Un champ obligatoire est manquant (par exemple `clientKey`, ou `websiteURL` / `websiteKey` pour le type de tâche), ou le corps de la requête n'est pas du JSON | Ajoutez les champs manquants indiqués sur la page du type de tâche, et envoyez du JSON avec `POST` et `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Compte pour la suspension) | Le corps de la requête n'est pas du JSON valide | Construisez le corps avec une bibliothèque JSON plutôt que par concaténation de chaînes ; le JSON ne doit pas contenir de commentaires `//` |
| `ERROR_TASK_ABSENT` (Compte pour la suspension) | Le champ `task` est manquant dans un appel à `createTask` | Placez les paramètres de la tâche dans un objet `task`. Avec Python requests, utilisez `json=data` et non `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Compte pour la suspension) | `task.type` est mal orthographié ou le type a été retiré | Copiez le nom du type depuis « Types de tâches et tarifs » ; les noms sont sensibles à la casse |
| `ERROR_PAGE_NOT_FOUND` | Le chemin demandé n'existe pas | Vérifiez l'URL de l'endpoint, par ex. `https://api.yescaptcha.com/createTask` ; les noms de méthodes sont sensibles à la casse |
| `ERROR_BAD_REQUEST` | La requête ne peut pas être traitée, généralement à cause d'une méthode HTTP incorrecte (GET au lieu de POST) ou de valeurs de paramètres invalides | Envoyez du JSON avec `POST`, et vérifiez les types et les valeurs des paramètres |
| `ERROR_ILLEGAL_PARAMETERS` | La valeur d'un paramètre est invalide. Cas typique pour la page de vérification Cloudflare : `websiteURL` n'est pas une URL publique en `http://` / `https://`, `postData` n'est pas un objet, ou `requiredCookies` n'est pas un tableau de chaînes (renvoyé par createTask, sans débit de points) ; ou le domaine cible n'a pas pu être résolu via le proxy (renvoyé par getTaskResult, remboursement de points automatique) | Corrigez la valeur en vous aidant du tableau des paramètres sur la page du type de tâche. Si le domaine n'a pas pu être résolu, vérifiez l'orthographe de l'URL et si le proxy peut accéder au site |

### Compte et solde

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Compte pour la suspension) | La `clientKey` n'existe pas : des caractères ont été ajoutés ou perdus lors de la copie, ou la clé a été réinitialisée dans le tableau de bord | Copiez à nouveau la clé depuis le tableau de bord de yescaptcha.com, sans espaces ni sauts de ligne |
| `ERROR_KEY_EXPIRED` (Compte pour la suspension) | La `clientKey` a expiré (renvoyée par createTask et getBalance, sans débit de points). Soit elle est restée inutilisée pendant longtemps et le système a défini une date d'expiration pour protéger le compte (un e-mail de rappel est envoyé avant l'expiration), soit la date d'expiration définie pour cette `clientKey` est dépassée | Connectez-vous au Tableau de bord de yescaptcha.com. Si elle a expiré après une longue période d'inutilisation, générez une nouvelle `clientKey` ; le solde est transféré automatiquement vers la nouvelle. Si une date d'expiration a été définie, modifiez-la ou utilisez une autre `clientKey`. Mettez ensuite à jour votre programme avec la nouvelle `clientKey` |
| `ERROR_KEY_IP_NOT_ALLOWED` | Ce `clientKey` a une liste d'adresses IP autorisées et l'IP d'où provient la requête n'y figure pas (renvoyée par createTask et getBalance, aucun débit de points, ne compte pas pour la suspension automatique) | Connectez-vous au Tableau de bord sur yescaptcha.com et ajoutez l'IP publique de la machine qui envoie les requêtes à la liste d'adresses autorisées de ce `clientKey`, ou utilisez un autre `clientKey`. Si plusieurs machines appellent l'API, ajoutez l'IP publique de chacune (il s'agit de l'IP qui appelle l'API YesCaptcha, pas du proxy indiqué dans les paramètres de la tâche) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Ce `clientKey` a une limite de dépenses et ce qu'il en reste pour la période en cours est inférieur au coût de cette tâche (renvoyée par createTask, aucun débit de points, ne compte pas pour la suspension automatique). La limite compte les points réellement débités ; les points remboursés pour les tâches échouées ou expirées sont recrédités à la limite | Connectez-vous au Tableau de bord sur yescaptcha.com et augmentez la limite de ce `clientKey`, attendez la période suivante (elle est remise à zéro chaque jour, chaque lundi ou le 1er de chaque mois, heure de Pékin ; une limite ponctuelle n'est pas remise à zéro), ou utilisez un autre `clientKey`. `getBalance` renvoie la limite restante de ce `clientKey` (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Solde insuffisant. Le solde doit être supérieur à 10 points pour créer une tâche | Rechargez votre compte puis réessayez. Utilisez `getBalance` pour consulter le solde |

### Tâches simultanées et suspensions

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Compte parfois pour la suspension) | Trop de tâches de ce type sont en cours pour le compte. `limit` dans la réponse est la limite actuelle. La requête n'a pas été traitée et aucun débit de points n'a eu lieu | Attendez que les requêtes en cours reviennent, ou attendez 1–2 secondes puis réessayez ; limitez le nombre de requêtes en attente simultanément |
| `ERROR_IP_BLOCKED_5MIN` | Cette `clientKey` a produit trop d'erreurs en peu de temps et a été suspendue automatiquement. `retryAfter` est le nombre de secondes restantes et `blockReason` est l'erreur à l'origine de la suspension | Corrigez la requête en fonction de `blockReason` et attendez `retryAfter` secondes ; envoyer des requêtes pendant la suspension ne la prolonge pas |
| `ERROR_NO_SLOT_AVAILABLE` | Le service de résolution est temporairement surchargé. Lorsque l'erreur est renvoyée par createTask, aucun point n'est débité ; une tâche restée trop longtemps dans la file d'attente la renvoie aussi depuis getTaskResult, et ses points sont remboursés automatiquement | Attendez quelques secondes, puis créez à nouveau la tâche |

### Tâches et résultats

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Compte pour la suspension) | Le `taskId` n'existe pas, a expiré (les résultats sont conservés environ 10 minutes), appartient à un autre `clientKey` ou a été créé sur l'autre endpoint | Arrêtez l'interrogation périodique (polling) de cette tâche. Interrogez-la avec le même endpoint et le même `clientKey` que ceux qui l'ont créée |
| `ERROR_TASK_TIMEOUT` | La tâche ne s'est pas terminée dans le délai imparti (généralement 110 secondes) ; les points ont été remboursés automatiquement | Créez une nouvelle tâche ; si le délai est systématiquement dépassé, essayez un autre type de tâche pour le même captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Le captcha n'a pas pu être résolu cette fois ; les points ont été remboursés. Cette erreur ne compte pas pour la suspension automatique | Créez une nouvelle tâche. Si les échecs persistent, vérifiez `websiteURL`, `websiteKey` et les autres paramètres, ou essayez un autre type de tâche pour le même captcha |
| `ERROR_SETTLEMENT_FAILED` (Compte pour la suspension) | Le solde était insuffisant lors du règlement, donc aucun résultat n'a été renvoyé | Rechargez votre compte, puis créez une nouvelle tâche |
| `ERROR_NO_SUCH_CAPCHA_ID` | La tâche n'est plus valide | Arrêtez l'interrogation périodique (polling) de cette tâche et créez-en une nouvelle |
| `ERROR_RECAPTCHA_TIMEOUT` | La résolution du captcha a expiré ; les points ont été remboursés | Créez une nouvelle tâche |

### Paramètres du site cible

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (En cache, sans suspension) | Le `websiteKey` est invalide | Retrouvez le sitekey dans la page (voir les guides pour trouver les paramètres). Pendant la période de cache, les requêtes identiques renvoient directement cette erreur, avec `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (En cache, sans suspension) | Le domaine de `websiteURL` ne correspond pas au `websiteKey` | Renseignez dans `websiteURL` la page qui affiche le captcha |
| `ERROR_INVALID_KEY_TYPE` (En cache, sans suspension) | Le sitekey appartient à un autre captcha, par exemple une clé v3 utilisée avec un type de tâche v2 | Identifiez d'abord le captcha (voir « Identifier le type de captcha »), puis choisissez le type de tâche correspondant ; pour la version v2 invisible, renseignez `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (En cache, sans suspension) | Ce site n'est pas pris en charge | Essayez un autre type de tâche pour le même captcha, ou contactez le support |
| `ERROR_HIGH_DEMAND_DOMAIN` (Compte pour la suspension) | Ce site n'est pas pris en charge | Arrêtez d'envoyer des tâches pour ce site et contactez le support |
| `ERROR_FAILED_LOADING_WIDGET` | Le captcha n'a pas pu être chargé avec les paramètres fournis | Vérifiez `websiteURL` et `websiteKey` ; pour les types de tâche avec votre propre proxy, vérifiez que le proxy peut accéder au site |

### Images

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Compte pour la suspension) | L'image est vide ou trop petite | Vérifiez que les données Base64 sont complètes et sans préfixe `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Compte pour la suspension) | L'image est trop volumineuse | Compressez ou réduisez l'image ; le corps complet de la requête ne doit pas dépasser 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Compte pour la suspension) | Le format de l'image n'est pas pris en charge, ou l'image n'est pas de celles que ce type de tâche peut traiter. Une seule occurrence suspend la clé pendant 30 minutes | Utilisez du JPG ou du PNG et vérifiez que l'image correspond au type de tâche, par exemple la reconnaissance d'images reCAPTCHA exige 100x100, 300x300 ou 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Compte pour la suspension) | La taille de l'image ne respecte pas les exigences de ce type de tâche | Redimensionnez l'image comme indiqué sur la page du type de tâche |
| `ERROR_PARSE_IMAGE_FAIL` | L'image n'a pas pu être décodée, souvent parce que le Base64 est tronqué ou comporte un préfixe | Vérifiez l'encodage Base64 et supprimez le préfixe `data:` ainsi que les sauts de ligne |
| `ERROR_UNKNOWN_QUESTION` | Le champ `question` est incorrect, ou cette question n'est pas encore prise en charge | Comparez-le avec la liste des questions de la page du type de tâche. Pour les questions non prises en charge, contactez le support ; les nouvelles questions sont généralement prises en charge sous 3 jours ouvrés |
| `ERROR_UNKNOW_450x450_QUESTION` | Cette question n'est pas encore prise en charge pour les images 4x4 (450x450) | Rechargez le défi dans la page pour obtenir une autre question |

### Proxys

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Le proxy a refusé la connexion | Vérifiez l'adresse, le port et le protocole du proxy, et assurez-vous qu'il accepte les connexions externes (pas une adresse locale comme 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | La connexion au proxy a expiré | Utilisez un proxy plus fiable |
| `ERROR_PROXY_READ_TIMEOUT` | La lecture via le proxy a expiré | Utilisez un proxy plus rapide |
| `ERROR_PROXY_BANNED` | Le proxy est indisponible, ou son IP est bloquée par le site cible | Utilisez un autre proxy |
| `ERROR_PROXY_INCORRECT` | Les paramètres du proxy sont mal formés | Vérifiez le format de `proxyType`, `proxyAddress`, `proxyPort` (ou de la chaîne `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | Le proxy est transparent et expose la vraie IP | Utilisez un proxy anonyme (élite) |
| `ERROR_PROXY_NOT_AUTHORISED` | Le nom d'utilisateur ou le mot de passe du proxy est incorrect | Vérifiez `proxyLogin` et `proxyPassword` (ou les identifiants dans la chaîne `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | La négociation TLS avec le proxy a échoué, souvent parce que `proxyType` est incorrect (par exemple https renseigné pour un proxy http) | Vérifiez le protocole du proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Impossible de se connecter au serveur proxy | Vérifiez l'adresse et le port du proxy, et assurez-vous que le proxy fonctionne |

### Serveur

| Code d'erreur | Signification | Que faire |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Le service est temporairement indisponible (le code s'écrit `UNAVALIABLE`) | Réessayez plus tard ; contactez le support si le problème persiste |
| `ERROR_INTERNAL_SERVER_ERROR` | Une erreur interne du serveur s'est produite | Réessayez plus tard ; si le problème persiste, contactez le support en indiquant le `taskId` |
| `ERROR_UNKNOWN` | Une erreur non classée | Réessayez plus tard ; si le problème persiste, contactez le support en indiquant le `taskId` |

## Champs supplémentaires

Certaines réponses d’erreur contiennent des champs supplémentaires :

| Champ | Présent avec | Description |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, erreurs en cache | Nombre de secondes à attendre |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Code d’erreur à l’origine de la suspension |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Type, URL et sitekey des requêtes à l’origine de la suspension, pour faciliter le diagnostic |
| `cached` | Erreurs en cache | `true` indique une réponse en cache, aucune reconnaissance n’a eu lieu |
| `badRequest` | Erreurs en cache | Paramètres ayant déclenché le cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Votre limite actuelle de tâches simultanées |

Pour la langue de `errorDescription`, voir [Requêtes et réponses](https://docs.yescaptcha.com/fr/api/overview.md).