# Requests and responses

> Common rules of the YesCaptcha API. POST JSON, clientKey authentication, the errorId response envelope, synchronous and asynchronous tasks, polling every 5 seconds, 110-second timeout, results kept about 10 minutes, message language by Accept-Language.

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

Every method takes an HTTPS `POST` with a JSON body (only `/useragent` is `GET`), is authenticated with the `clientKey` in the body, and returns JSON: `errorId` 0 means success, 1 means failure with an `errorCode`. Solving a captcha takes two steps: `createTask` creates a task and `getTaskResult` is polled every 5 seconds for the result. Synchronous types return the result from `createTask` directly.

## Request

```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` (global) or `https://cn.yescaptcha.com` (China). See [Endpoints](https://docs.yescaptcha.com/en/getting-started/endpoints/).
-   The body is JSON, sent with `Content-Type: application/json`, under 6 MB. JSON cannot contain comments.
-   Every request includes `clientKey`, copied in full from the dashboard.
-   With Python requests use `json=data`, not `data=data` (the latter sends a form and returns `ERROR_TASK_ABSENT` or `ERROR_REQUIRED_FIELDS`).

## Response

Success:

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

Failure:

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

| Field | Description |
| --- | --- |
| `errorId` | 0 success, 1 failure |
| `errorCode` | The error code on failure; meanings and fixes in [Error codes](https://docs.yescaptcha.com/en/api/errors/) |
| `errorDescription` | A text description of the failure (Chinese for most codes) |
| `taskId` | The task ID |
| `status` | `processing` or `ready` |
| `solution` | The result; its fields depend on the task type (see each task type page) |

Check `errorId` and `errorCode` in your code, not the wording of `errorDescription`, which may change.

## Synchronous and asynchronous

|  | Asynchronous | Synchronous |
| --- | --- | --- |
| Which types | Token types (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), the Cloudflare challenge page, `ImageToTextTask`, `ImageToTextTaskM1` | Image recognition (names ending in `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` returns | `taskId` | `status: "ready"` and `solution` |
| Getting the result | Call `getTaskResult` every 5 seconds | Nothing more to do |

The “Mode” column in [Task types and pricing](https://docs.yescaptcha.com/en/tasks/) shows which applies to each type.

## Polling

1.  After `createTask` returns a `taskId`, wait 5 seconds and call `getTaskResult`.
2.  On `status: "processing"`, wait another 5 seconds and try again; on `status: "ready"`, the result is in `solution`.
3.  On `errorId: 1`, stop polling this task and handle the `errorCode`.

-   Repeated queries for the same `taskId` within 5 seconds return `processing` right away; polling faster does not get the result sooner.
-   A task runs for at most about 110 seconds (180 to 220 seconds for a few types); after that it returns `ERROR_TASK_TIMEOUT` and the points are refunded.
-   Results are kept for about 10 minutes; after that the `taskId` expires and queries return `ERROR_TASKID_INVALID`.
-   Queries are free; only creating a task is charged.

## Message language

For automatic pauses, cached invalid parameters and stop-polling hints, `errorDescription` follows the `Accept-Language` request header: Chinese if it starts with `zh`, English for any other language, and both if the header is absent. Other error descriptions are unaffected.

## Next

-   [createTask](https://docs.yescaptcha.com/en/api/create-task/)
-   [getTaskResult](https://docs.yescaptcha.com/en/api/get-task-result/)
-   [Rate limits](https://docs.yescaptcha.com/en/api/rate-limits/): too many errors pause your key for a few minutes