# Códigos de error

> Significado y forma de resolver todos los códigos de error de la API de YesCaptcha: formato de la solicitud, cuenta y saldo, tareas simultáneas y pausas, resultado de la tarea, parámetros del sitio, imágenes, proxy y servidor. Las solicitudes que devuelven error no cobran puntos.

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

Cuando la API falla, devuelve `errorId: 1`; `errorCode` es el código de error y `errorDescription` es la descripción en texto. Las solicitudes que devuelven error no cobran puntos: si el error ocurre al crear la tarea no se cobra nada, y si el reconocimiento falla o se agota el tiempo después de crearla, los puntos se reembolsan automáticamente.

> **Consejo:** En tu programa, decide según `errorCode`, no según el texto de `errorDescription`, ya que la descripción puede cambiar.

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

## Cómo manejar los errores

1.  **Los errores de parámetros** (formato de la solicitud, ClientKey, tipo de tarea, parámetros del sitio, imágenes) no cambian al reenviar la solicitud; primero corrígela.
2.  **Los fallos de reconocimiento y los tiempos agotados** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) se pueden resolver creando una tarea nueva.
3.  Tras un error, **deja de consultar** ese `taskId`; no reenvíes la misma solicitud a alta frecuencia.
4.  Con los errores marcados como “cuenta para la pausa automática”, si un mismo `clientKey` acumula 100 en un minuto, se pausa la creación de tareas durante 5 minutos. Los marcados como “caché” no cuentan, pero mientras dura la caché las solicitudes idénticas devuelven directamente el mismo error. Más detalles en [Límite de tareas simultáneas y pausa automática](https://docs.yescaptcha.com/es/api/rate-limits.md).

## Todos los códigos de error

### Formato de la solicitud

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Falta un campo obligatorio (como `clientKey`, o `websiteURL` / `websiteKey` para el tipo de tarea), o el cuerpo de la solicitud no es JSON | Añade los campos que faltan indicados en la página del tipo de tarea, y envía JSON con `POST` y `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Cuenta para la pausa) | El cuerpo de la solicitud no es un JSON válido | Genera el cuerpo con una biblioteca de JSON en lugar de concatenar cadenas; el JSON no puede contener comentarios `//` |
| `ERROR_TASK_ABSENT` (Cuenta para la pausa) | Falta el campo `task` en una llamada a `createTask` | Coloca los parámetros de la tarea en un objeto `task`. Con Python requests usa `json=data`, no `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Cuenta para la pausa) | `task.type` está mal escrito o el tipo ya fue dado de baja | Copia el nombre del tipo desde "Tipos de tarea y precios"; los nombres distinguen entre mayúsculas y minúsculas |
| `ERROR_PAGE_NOT_FOUND` | La ruta solicitada no existe | Revisa la URL del endpoint, p. ej., `https://api.yescaptcha.com/createTask`; los nombres de los métodos distinguen entre mayúsculas y minúsculas |
| `ERROR_BAD_REQUEST` | No se puede procesar la solicitud, normalmente por un método HTTP incorrecto (GET en lugar de POST) o por valores de parámetros no válidos | Envía JSON con `POST` y revisa los tipos y valores de los parámetros |
| `ERROR_ILLEGAL_PARAMETERS` | El valor de un parámetro no es válido. Es típico en la página de verificación de Cloudflare: `websiteURL` no es una URL pública que empiece por `http://` / `https://`, `postData` no es un objeto, o `requiredCookies` no es un arreglo de cadenas (lo devuelve createTask, sin cobro de puntos); o no se pudo resolver el dominio de destino a través del proxy (lo devuelve getTaskResult, con reembolso de puntos automático) | Corrige el valor según la tabla de parámetros de la página del tipo de tarea. Si no se pudo resolver el dominio, revisa la ortografía de la URL y si el proxy puede acceder al sitio |

### Cuenta y saldo

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Cuenta para la pausa) | El `clientKey` no existe: se añadieron o perdieron caracteres al copiarlo, o la clave se restableció en el Panel | Vuelve a copiar la clave desde el Panel de yescaptcha.com, sin espacios ni saltos de línea |
| `ERROR_KEY_EXPIRED` (Cuenta para la pausa) | El `clientKey` ha expirado (lo devuelven createTask y getBalance, sin cobro de puntos). Puede ser que no se haya usado durante mucho tiempo y el sistema haya fijado una fecha de expiración para proteger la cuenta (se envía un recordatorio por correo antes de que expire), o que haya pasado la fecha de expiración configurada para este `clientKey` | Inicia sesión en el Panel de yescaptcha.com. Si expiró por llevar mucho tiempo sin usarse, genera un nuevo `clientKey`; el saldo se transfiere automáticamente al nuevo. Si se configuró una fecha de expiración, cámbiala o usa otro `clientKey`. Después, actualiza tu programa con el nuevo `clientKey` |
| `ERROR_KEY_IP_NOT_ALLOWED` | Este `clientKey` tiene una lista de IP permitidas y la IP desde la que se envió la solicitud no está en ella (lo devuelven createTask y getBalance, no se hace cobro de puntos, no cuenta para la pausa automática) | Inicia sesión en el Panel de yescaptcha.com y agrega la IP pública de la máquina que envía las solicitudes a la lista de IP permitidas de este `clientKey`, o usa otro `clientKey`. Si varias máquinas llaman a la API, agrega la IP pública de cada una (es la IP que llama a la API de YesCaptcha, no el proxy de los parámetros de la tarea) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Este `clientKey` tiene un límite de gasto y lo que queda de él en el período actual es menor que el costo de esta tarea (lo devuelve createTask, no se hace cobro de puntos, no cuenta para la pausa automática). El límite cuenta los puntos realmente cobrados; los puntos reembolsados por tareas fallidas o con tiempo agotado vuelven al límite | Inicia sesión en el Panel de yescaptcha.com y aumenta el límite de este `clientKey`, espera al siguiente período (se restablece cada día, cada lunes o el día 1 de cada mes, hora de Beijing; un límite único no se restablece), o usa otro `clientKey`. `getBalance` devuelve el límite restante de este `clientKey` (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Saldo insuficiente. El saldo debe ser superior a 10 puntos para crear una tarea | Recarga y vuelve a intentarlo. Usa `getBalance` para consultar el saldo |

### Tareas simultáneas y pausas

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (A veces cuenta para la pausa) | Hay demasiadas tareas de este tipo en curso para la cuenta. `limit` en la respuesta es el límite actual. La solicitud no se procesó y no hubo cobro de puntos | Espera a que terminen las solicitudes en curso, o espera 1–2 segundos y vuelve a intentarlo; limita el número de solicitudes que esperan al mismo tiempo |
| `ERROR_IP_BLOCKED_5MIN` | Este `clientKey` generó demasiados errores en poco tiempo y se aplicó una pausa automática. `retryAfter` son los segundos restantes y `blockReason` es el error que la causó | Corrige la solicitud según `blockReason` y espera `retryAfter` segundos; enviar solicitudes durante la pausa no la prolonga |
| `ERROR_NO_SLOT_AVAILABLE` | El servicio de resolución está temporalmente saturado. Cuando lo devuelve createTask, no se cobra nada; una tarea que esperó demasiado en la cola también lo devuelve desde getTaskResult, y se le hace un reembolso de puntos automático | Espera unos segundos y crea la tarea de nuevo |

### Tareas y resultados

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Cuenta para la pausa) | El `taskId` no existe, ha expirado (los resultados se conservan unos 10 minutos), pertenece a otro `clientKey` o se creó en el otro endpoint | Deja de hacer consultas periódicas (polling) de esta tarea. Consulta con el mismo endpoint y el mismo `clientKey` con el que se creó |
| `ERROR_TASK_TIMEOUT` | La tarea no terminó a tiempo (normalmente 110 segundos); los puntos se reembolsaron automáticamente | Crea una tarea nueva; si sigue agotando el tiempo, prueba otro tipo de tarea para el mismo captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Esta vez no se pudo resolver el captcha; los puntos se reembolsaron. No cuenta para la pausa automática | Crea una tarea nueva. Si sigue fallando, revisa `websiteURL`, `websiteKey` y los demás parámetros, o prueba otro tipo de tarea para el mismo captcha |
| `ERROR_SETTLEMENT_FAILED` (Cuenta para la pausa) | El saldo era insuficiente al momento del cobro, por lo que no se devolvió ningún resultado | Recarga y crea una tarea nueva |
| `ERROR_NO_SUCH_CAPCHA_ID` | La tarea ya no es válida | Deja de hacer consultas periódicas (polling) de esta tarea y crea una nueva |
| `ERROR_RECAPTCHA_TIMEOUT` | Se agotó el tiempo al resolver el captcha; los puntos se reembolsaron | Crea una tarea nueva |

### Parámetros del sitio de destino

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (En caché, no cuenta para la pausa) | El `websiteKey` no es válido | Vuelve a buscar el sitekey en la página (consulta las guías para encontrar parámetros). Las solicitudes idénticas devuelven este error directamente durante el periodo de caché, con `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (En caché, no cuenta para la pausa) | El dominio de `websiteURL` no coincide con el `websiteKey` | Establece `websiteURL` con la página que muestra el captcha |
| `ERROR_INVALID_KEY_TYPE` (En caché, no cuenta para la pausa) | El sitekey pertenece a otro captcha, por ejemplo una clave de v3 usada con un tipo de tarea de v2 | Identifica primero el captcha (consulta "Identificar el tipo de captcha") y elige el tipo de tarea correspondiente; para v2 invisible indica `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (En caché, no cuenta para la pausa) | Este sitio no es compatible | Prueba otro tipo de tarea para el mismo captcha o contacta a soporte |
| `ERROR_HIGH_DEMAND_DOMAIN` (Cuenta para la pausa) | Este sitio no es compatible | Deja de enviar tareas para este sitio y contacta a soporte |
| `ERROR_FAILED_LOADING_WIDGET` | No se pudo cargar el captcha con los parámetros indicados | Revisa `websiteURL` y `websiteKey`; en los tipos de tarea con proxy propio, comprueba que el proxy pueda acceder al sitio |

### Imágenes

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Cuenta para la pausa) | La imagen está vacía o es demasiado pequeña | Comprueba que los datos en Base64 estén completos y no tengan el prefijo `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Cuenta para la pausa) | La imagen es demasiado grande | Comprime o reduce la imagen; el cuerpo completo de la solicitud no debe superar 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Cuenta para la pausa) | El formato de la imagen no es compatible, o la imagen no es de las que este tipo de tarea puede procesar. Una sola aparición pausa la clave durante 30 minutos | Usa JPG o PNG y asegúrate de que la imagen corresponda al tipo de tarea; por ejemplo, el reconocimiento de imágenes de reCAPTCHA requiere 100x100, 300x300 o 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Cuenta para la pausa) | El tamaño de la imagen no cumple los requisitos de este tipo de tarea | Cambia el tamaño de la imagen como se describe en la página del tipo de tarea |
| `ERROR_PARSE_IMAGE_FAIL` | No se pudo decodificar la imagen, a menudo porque el Base64 está truncado o tiene un prefijo | Revisa la codificación Base64 y elimina el prefijo `data:` y los saltos de línea |
| `ERROR_UNKNOWN_QUESTION` | La `question` es incorrecta, o esta pregunta aún no es compatible | Compárala con la lista de preguntas de la página del tipo de tarea. Si una pregunta no es compatible, contacta a soporte; las preguntas nuevas normalmente se admiten en 3 días hábiles |
| `ERROR_UNKNOW_450x450_QUESTION` | Esta pregunta aún no es compatible con imágenes de 4x4 (450x450) | Recarga el desafío en la página para obtener otra pregunta |

### Proxies

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | El proxy rechazó la conexión | Revisa la dirección, el puerto y el protocolo del proxy, y asegúrate de que acepte conexiones externas (no una dirección local como 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Se agotó el tiempo al conectar con el proxy | Usa un proxy más estable |
| `ERROR_PROXY_READ_TIMEOUT` | Se agotó el tiempo al leer datos a través del proxy | Usa un proxy más rápido |
| `ERROR_PROXY_BANNED` | El proxy no está disponible, o su IP está bloqueada por el sitio de destino | Usa otro proxy |
| `ERROR_PROXY_INCORRECT` | Los parámetros del proxy tienen un formato incorrecto | Revisa el formato de `proxyType`, `proxyAddress`, `proxyPort` (o de la cadena `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | El proxy es transparente y expone la IP real | Usa un proxy anónimo (de alto anonimato) |
| `ERROR_PROXY_NOT_AUTHORISED` | El usuario o la contraseña del proxy son incorrectos | Revisa `proxyLogin` y `proxyPassword` (o las credenciales en la cadena `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | Falló el handshake TLS con el proxy, a menudo porque `proxyType` es incorrecto (por ejemplo, https indicado para un proxy http) | Revisa el protocolo del proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | No se pudo conectar con el servidor proxy | Revisa la dirección y el puerto del proxy y asegúrate de que funcione correctamente |

### Servidor

| Código de error | Significado | Qué hacer |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | El servicio no está disponible temporalmente (el código se escribe `UNAVALIABLE`) | Inténtalo de nuevo más tarde; contacta a soporte si persiste |
| `ERROR_INTERNAL_SERVER_ERROR` | Ocurrió un error interno del servidor | Vuelve a intentarlo más tarde; si persiste, contacta con Soporte e indica el `taskId` |
| `ERROR_UNKNOWN` | Un error sin clasificar | Vuelve a intentarlo más tarde; si persiste, contacta con Soporte e indica el `taskId` |

## Campos adicionales

Algunas respuestas de error incluyen campos adicionales:

| Campo | Aparece en | Descripción |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, errores en caché | Segundos que faltan por esperar |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Código de error que provocó la pausa |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Tipo, URL y sitekey de las solicitudes que provocaron la pausa, para facilitar la localización |
| `cached` | Errores en caché | `true` indica que es un resultado en caché y no hubo reconocimiento real |
| `badRequest` | Errores en caché | Parámetros que coincidieron con la caché |
| `limit` | `ERROR_THREADS_MAXIMUM` | Tu límite actual de tareas simultáneas |

Las reglas sobre el idioma de `errorDescription` están en [Solicitudes y respuestas](https://docs.yescaptcha.com/es/api/overview.md).