Codes d'erreur

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.

{
  "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.

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.