Códigos de error

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.

{
  "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.

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.