# Requêtes et réponses

> Conventions communes de l'API YesCaptcha : POST JSON, authentification par clientKey, format de réponse avec errorId, tâches synchrones et asynchrones, interrogation toutes les 5 secondes, délai maximal de 110 secondes, résultats conservés environ 10 minutes, langue des messages selon Accept-Language.

Source: https://docs.yescaptcha.com/fr/api/overview/ · 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/overview/

Toutes les méthodes reçoivent un `POST` HTTPS avec un corps JSON (seul `/useragent` est en `GET`), s’authentifient avec le `clientKey` du corps de la requête et renvoient du JSON : `errorId` à 0 signifie un succès, à 1 un échec accompagné d’un `errorCode`. Résoudre un captcha se fait en deux étapes : `createTask` crée la tâche, puis `getTaskResult` est interrogé toutes les 5 secondes pour obtenir le résultat. Les types synchrones renvoient directement le résultat dans `createTask`.

## Requête

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```

-   Endpoint : `https://api.yescaptcha.com` (mondial) ou `https://cn.yescaptcha.com` (Chine). Voir [Adresses d’accès](https://docs.yescaptcha.com/fr/getting-started/endpoints.md).
-   Le corps est au format JSON, envoyé avec l’en-tête `Content-Type: application/json`, et ne dépasse pas 6 MB. Le JSON ne peut pas contenir de commentaires.
-   Chaque requête doit inclure `clientKey`, copié en entier depuis le tableau de bord.

> **Attention:** Avec requests en Python, utilisez `json=data` et non `data=data`. Ce dernier envoie un formulaire et renvoie `ERROR_TASK_ABSENT` ou `ERROR_REQUIRED_FIELDS`.

## Réponse

Succès :

```json
{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```

Échec :

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

| Champ | Description |
| --- | --- |
| `errorId` | 0 : succès, 1 : échec |
| `errorCode` | Code d’erreur en cas d’échec ; signification et solutions dans [Codes d’erreur](https://docs.yescaptcha.com/fr/api/errors.md) |
| `errorDescription` | Description textuelle de la cause de l’échec |
| `taskId` | ID de tâche |
| `status` | `processing` (en cours) ou `ready` (terminé) |
| `solution` | Résultat de la résolution ; les champs dépendent du type de tâche (voir la page de chaque type de tâche) |

Dans votre code, appuyez-vous sur `errorId` et `errorCode`, pas sur le texte de `errorDescription`, qui peut changer.

## Synchrone et asynchrone

|  | Asynchrone | Synchrone |
| --- | --- | --- |
| Types concernés | Types qui renvoient un token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), page de vérification Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Reconnaissance d’images (noms se terminant par `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` renvoie | `taskId` | `status: "ready"` et `solution` |
| Obtenir le résultat | Appelez `getTaskResult` toutes les 5 secondes | Rien de plus à faire |

La colonne « Mode de retour » de [Types de tâches et prix](https://docs.yescaptcha.com/fr/tasks.md) indique le mode de chaque type.

## Interrogation périodique (polling)

1.  Une fois le `taskId` renvoyé par `createTask`, attendez 5 secondes avant d’appeler `getTaskResult`.
2.  Si la réponse est `status: "processing"`, attendez encore 5 secondes puis réessayez ; si elle est `status: "ready"`, le résultat se trouve dans `solution`.
3.  Si la réponse est `errorId: 1`, arrêtez d’interroger cette tâche et traitez l’`errorCode`.

-   Les requêtes répétées pour le même `taskId` dans un délai de 5 secondes renvoient immédiatement `processing` ; interroger plus souvent ne donne pas le résultat plus vite.
-   Une tâche est traitée au maximum pendant environ 110 secondes (180 à 220 secondes pour quelques types) ; passé ce délai, elle renvoie `ERROR_TASK_TIMEOUT` et les points sont remboursés automatiquement.
-   Les résultats sont conservés côté serveur environ 10 minutes ; ensuite le `taskId` expire et la requête renvoie `ERROR_TASKID_INVALID`.
-   La consultation du résultat n’entraîne aucun débit de points ; seule la création de la tâche est débitée.

## Langue des messages

Pour les messages de suspension automatique, de paramètres invalides mis en cache et d’arrêt de l’interrogation, `errorDescription` suit l’en-tête de requête `Accept-Language` : chinois si la valeur commence par `zh`, anglais pour toute autre langue, et les deux langues si l’en-tête est absent. Les descriptions des autres codes d’erreur ne sont pas concernées.

## Étape suivante

-   [createTask : créer une tâche](https://docs.yescaptcha.com/fr/api/create-task.md)
-   [getTaskResult : obtenir le résultat](https://docs.yescaptcha.com/fr/api/get-task-result.md)
-   [Limite de tâches simultanées et suspension automatique](https://docs.yescaptcha.com/fr/api/rate-limits.md) : trop d’erreurs entraînent une suspension de quelques minutes