# Solicitudes y respuestas

> Convenciones comunes de la API de YesCaptcha. POST con JSON, autenticación con ClientKey, formato de respuesta con errorId, tareas síncronas y asíncronas, consulta periódica (polling) cada 5 segundos, timeout de 110 segundos, resultados guardados unos 10 minutos e idioma de los mensajes según Accept-Language.

Source: https://docs.yescaptcha.com/es/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/

Todos los métodos usan HTTPS `POST` con un cuerpo JSON (solo `/useragent` es `GET`), se autentican con el `clientKey` del cuerpo y devuelven JSON: `errorId` 0 significa éxito y 1 significa fallo, con un `errorCode`. Resolver un captcha tiene dos pasos: `createTask` crea la tarea y `getTaskResult` se consulta cada 5 segundos para obtener el resultado. Los tipos síncronos devuelven el resultado directamente en `createTask`.

## Solicitud

```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) o `https://cn.yescaptcha.com` (China). Consulta [Direcciones de acceso](https://docs.yescaptcha.com/es/getting-started/endpoints.md).
-   El cuerpo es JSON, se envía con el encabezado `Content-Type: application/json` y no puede superar 6 MB. El JSON no admite comentarios.
-   Cada solicitud debe incluir `clientKey`, copiado completo desde el Panel.

> **Precaución:** Con requests de Python usa `json=data`, no `data=data`. Esta última envía un formulario y devuelve `ERROR_TASK_ABSENT` o `ERROR_REQUIRED_FIELDS`.

## Respuesta

Éxito:

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

Fallo:

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

| Campo | Descripción |
| --- | --- |
| `errorId` | 0 éxito, 1 fallo |
| `errorCode` | Código de error en caso de fallo; su significado y cómo resolverlo están en [Códigos de error](https://docs.yescaptcha.com/es/api/errors.md) |
| `errorDescription` | Descripción en texto del motivo del fallo |
| `taskId` | ID de tarea |
| `status` | `processing` (en proceso) o `ready` (completada) |
| `solution` | Resultado del reconocimiento; sus campos dependen del tipo de tarea (consulta la página de cada tipo) |

Para evaluar el resultado, usa `errorId` y `errorCode`; no analices el texto de `errorDescription`, ya que puede cambiar.

## Síncrono y asíncrono

|  | Asíncrono | Síncrono |
| --- | --- | --- |
| Qué tipos | Tipos que devuelven token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), página de verificación de Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Reconocimiento de imágenes (nombres que terminan en `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` devuelve | `taskId` | `status: "ready"` y `solution` |
| Cómo obtener el resultado | Llama a `getTaskResult` cada 5 segundos | No hace falta consultar de nuevo |

Para saber a qué grupo pertenece cada tipo, consulta la columna “Modo de respuesta” de [Tipos de tarea y precios](https://docs.yescaptcha.com/es/tasks.md).

## Consulta periódica (polling)

1.  Cuando `createTask` devuelva un `taskId`, espera 5 segundos y llama a `getTaskResult`.
2.  Si devuelve `status: "processing"`, espera otros 5 segundos y reintenta; si devuelve `status: "ready"`, el resultado está en `solution`.
3.  Si devuelve `errorId: 1`, deja de consultar esa tarea y gestiona el `errorCode`.

-   Las consultas repetidas del mismo `taskId` dentro de 5 segundos devuelven `processing` de inmediato; consultar con más frecuencia no da el resultado antes.
-   Una tarea se procesa como máximo unos 110 segundos (180 a 220 segundos en algunos tipos); si se supera, devuelve `ERROR_TASK_TIMEOUT` y se hace el reembolso de puntos automáticamente.
-   El resultado se guarda en el servidor unos 10 minutos; después el `taskId` caduca y la consulta devuelve `ERROR_TASKID_INVALID`.
-   Consultar el resultado no cobra puntos; solo se cobran al crear la tarea.

## Idioma de los mensajes

En los avisos de pausa automática, caché de parámetros inválidos y fin de la consulta periódica, `errorDescription` se elige según el encabezado `Accept-Language`: si empieza por `zh` se devuelve en chino, con cualquier otro idioma se devuelve en inglés, y si no se envía el encabezado se devuelven ambos. Las descripciones de los demás códigos de error no cambian.

## Siguiente paso

-   [createTask: crear una tarea](https://docs.yescaptcha.com/es/api/create-task.md)
-   [getTaskResult: obtener el resultado](https://docs.yescaptcha.com/es/api/get-task-result.md)
-   [Límite de tareas simultáneas y pausa automática](https://docs.yescaptcha.com/es/api/rate-limits.md): si hay demasiados errores, se pausa tu cuenta unos minutos