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.

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.