Référence

Codes d'erreur

Toutes les erreurs renvoyées par l'API, leur signification et la conduite à tenir.

Le HTTP est toujours 200, y compris pour les erreurs. C'est le contrat anti-captcha et nous le respectons : un client écrit pour CapSolver n'a pas besoin de réécrire sa gestion d'erreurs. Testez errorId : 0 signifie succès, 1 signifie lire errorCode.

Forme d'une réponse en erreur

{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "No API key matches that clientKey."
}

Code	Signification	Que faire
`ERROR_KEY_DOES_NOT_EXIST`	Aucune clé API ne correspond au clientKey envoyé.	Vérifiez une erreur de copier-coller ou une variable d'environnement périmée. Les clés ne sont affichées en entier qu'une seule fois, à la création.
`ERROR_ZERO_BALANCE`	Votre portefeuille ne peut pas couvrir le prix de la tâche.	Rechargez. Les tâches déjà en cours ne sont pas affectées et restent remboursées si elles échouent.
`ERROR_TASK_TYPE_NOT_SUPPORTED`	La valeur de task.type ne fait pas partie de celles que nous traitons.	Comparez-la à la référence des types de tâches. La valeur est insensible à la casse mais l'orthographe doit être exacte.
`ERROR_NO_SUCH_TASK`	Ce taskId n'existe pas, ou n'appartient pas à votre clé.	Les résultats sont conservés 5 minutes après la fin de la tâche. Interrogez plus tôt, et ne partagez jamais un taskId entre deux comptes.
`ERROR_RATE_LIMIT`	Trop de requêtes dans la fenêtre courante.	Ralentissez et réessayez. La tâche elle-même n'est pas affectée : gardez le même taskId et continuez à interroger.
`ERROR_KEY_DISABLED`	La clé existe mais a été désactivée.	Réactivez-la depuis le tableau de bord, ou générez-en une nouvelle. Une clé est désactivée par vous, ou par nous après une enquête sur l'usage acceptable.
`ERROR_UPSTREAM`	Le solveur a refusé cette tâche ou a échoué dessus.	Vous avez été remboursé. Réessayez une fois ; si cela se répète sur la même cible, envoyez-nous la sitekey et l'URL de la page.
`ERROR_TIMEOUT`	La tâche ne s'est pas résolue avant son échéance.	Vous avez été remboursé. Les cibles durcies demandent parfois un proxy ou un User-Agent exact — essayez la variante avec proxy du type de tâche.

Codes de résultat de solve

Les codes ci-dessus viennent de la passerelle — votre clé, votre solde, votre limite de débit. Quand le solve lui-même échoue, le code du solveur passe directement. Vous êtes toujours remboursé ; la colonne action indique si réessayer en vaut la peine et, quand la cause est votre proxy, que c'est à vous de le corriger.

Code	Signification	Que faire
`CAPTCHA_UNSOLVABLE`	Le solve a bien eu lieu mais nous n'avons pas pu produire de token ou de cookie valide pour cette cible.	Remboursé. Réessayez une fois ; si ça se répète sur le même sitekey, envoyez-le-nous — certaines cibles sont réellement difficiles.
`TASK_TIMEOUT`	Le solve ne s'est pas terminé dans son délai.	Remboursé. Souvent une cible lente ou surchargée ; réessayez, et sur un site durci fournissez un proxy résidentiel.
`CHALLENGE_NOT_PRESENT`	Pour une tâche cookie Cloudflare, la page a été servie directement — il n'y avait aucun challenge à passer sur cette IP.	Remboursé, et rien à faire : la page est déjà accessible depuis cette IP. Le challenge se déclenche sur les IP datacenter, pas sur du résidentiel propre.
`PROXY_BANNED`	La cible a bouclé son challenge Cloudflare sans jamais émettre de token — cette IP de sortie est refusée par le site.	Remboursé. Réessayez avec un proxy de meilleure réputation (résidentiel ou mobile). Réessayer la même IP refusée ne sert à rien.
`PROXY_CONNECTION_FAILED`	Nous n'avons pas pu ouvrir de connexion via le proxy que vous avez fourni.	Remboursé. Vérifiez l'hôte, le port et que le proxy est en ligne. C'est votre proxy, pas la cible.
`PROXY_AUTH_FAILED`	Le proxy a rejeté les identifiants fournis.	Remboursé. Vérifiez proxyLogin et proxyPassword.
`PROXY_INCOMPATIBLE`	Le proxy n'a pas pu porter la requête — souvent SOCKS uniquement, transparent, ou un certificat TLS cassé.	Remboursé. Utilisez un proxy HTTP(S) qui supporte le tunnel CONNECT.
`INVALID_SITEKEY`	Le websiteKey a été rejeté par la cible — erroné, expiré, ou pour un autre domaine.	Remboursé. Copiez le sitekey depuis le code source de l'URL exacte que vous résolvez.
`INVALID_USERAGENT`	Le userAgent envoyé n'est pas un User-Agent de navigateur actuel.	Remboursé. Envoyez un vrai UA de navigateur récent, ou omettez le champ et nous utilisons le nôtre.
`INVALID_TASK_DATA`	Un champ requis par le type de tâche est manquant ou malformé (par exemple un websiteKey sur une tâche widget).	Remboursé. Vérifiez le tableau des champs de create-task pour le type que vous envoyez.

Les traiter

Deux codes seulement méritent une reprise automatique. ERROR_RATE_LIMIT signifie ralentir et conserver la même tâche. ERROR_UPSTREAM et ERROR_TIMEOUT signifient que la tâche est morte et remboursée — réessayez en en créant une nouvelle, une fois au maximum, sinon vous dépenserez votre budget sur une cible qui ne se résoudra pas. Tout le reste demande un humain.

const result = await post('/getTaskResult', { taskId });

if (result.errorId !== 0) {
  switch (result.errorCode) {
    case 'ERROR_RATE_LIMIT':
      // Back off and retry the same taskId — the task is still alive.
      await sleep(2000);
      continue;
    case 'ERROR_ZERO_BALANCE':
    case 'ERROR_KEY_DISABLED':
      // Nothing to retry. Alert an operator.
      throw new Error(result.errorDescription);
    default:
      // Refunded already; create a fresh task if it is worth retrying.
      throw new Error(`${result.errorCode}: ${result.errorDescription}`);
  }
}

Une réponse en erreur ne vous laisse jamais débité. Si vous constatez un débit sans crédit correspondant pour une tâche en échec, c'est un bug : envoyez-nous l'identifiant de tâche, nous corrigeons et remboursons.