Límite de tareas simultáneas y pausa automática

Para mantener la velocidad de reconocimiento para todos los usuarios, YesCaptcha tiene tres reglas de protección: limita por cuenta el número de tareas en proceso a la vez (límite de tareas simultáneas); pausa durante unos minutos un clientKey que genera demasiados errores en poco tiempo (pausa automática); y devuelve directamente el error original, durante un tiempo, para los parámetros ya considerados no válidos (caché de parámetros no válidos). En ninguno de los tres casos se cobran puntos.

Límite de tareas simultáneas

Limitamos, por cuenta y por tipo de tarea, el número de tareas que se procesan al mismo tiempo. Se limita la simultaneidad, no el número de solicitudes por minuto.

• Una tarea cuenta como “en proceso” desde que llamas a createTask hasta que esa llamada devuelve la respuesta. Los tipos de reconocimiento de imágenes devuelven el resultado directamente en createTask, así que tareas simultáneas ≈ tareas enviadas por segundo × duración de cada tarea. Por ejemplo, con 0.5 segundos por tarea y 40 tareas por segundo, hay unas 20 tareas simultáneas.
• Las solicitudes de una misma cuenta se suman; cada tipo de tarea se cuenta por separado.
• Las solicitudes que superan el límite devuelven de inmediato ERROR_THREADS_MAXIMUM, y el campo limit de la respuesta indica tu límite actual. No se cobran puntos ni cuenta para la pausa automática.
• Cuando los servidores de reconocimiento están saturados, a la cuenta que más tiempo de reconocimiento consume se le reduce temporalmente a la mitad el límite de ese tipo de tarea, y se restablece automáticamente a los 10 minutos. Solo reduce la velocidad; no pausa la cuenta.
• Si necesitas un límite mayor, contacta con Soporte. Cuando se definan los límites predeterminados de cada tipo, se publicarán en esta página y en el registro de actualizaciones del servicio.

{
  "errorId": 1,
  "errorCode": "ERROR_THREADS_MAXIMUM",
  "errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
  "limit": 30
}

(Los números del ejemplo son solo ilustrativos.)

Recomendaciones

1. En tu programa, limita el número de solicitudes que esperan resultado a la vez, por ejemplo con un semáforo (Semaphore) o un pool de hilos de tamaño fijo, en lugar de controlar solo cuántas envías por segundo.
2. Tras recibir ERROR_THREADS_MAXIMUM, espera a que las solicitudes ya enviadas devuelvan su respuesta antes de enviar nuevas, o espera de 1 a 2 segundos y vuelve a intentarlo. No reintentes de inmediato en un bucle.
3. Envía las tareas por lotes de forma uniforme; no envíes miles de tareas de golpe.

Ejemplo en Python (asyncio):

import asyncio
import os

import aiohttp

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15  # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)


async def solve(session, task):
    async with sem:  # at most LIMIT requests in progress at a time
        result = {}
        for attempt in range(5):
            async with session.post(
                "https://api.yescaptcha.com/createTask",
                json={"clientKey": CLIENT_KEY, "task": task},
            ) as resp:
                result = await resp.json()
            if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
                return result
            await asyncio.sleep(1 + attempt)  # over the limit: wait and retry
        return result

Pausa automática

Si un mismo clientKey genera muchas solicitudes con error en poco tiempo, se le pausa automáticamente la creación de tareas:

Condición	Duración de la pausa
100 de los errores indicados abajo dentro del mismo minuto natural	5 minutos
1 vez ERROR_IMAGE_TYPE_NOT_SUPPORTED	30 minutos
1000 coincidencias con la “caché de parámetros no válidos” dentro del mismo minuto natural	5 minutos

Errores que cuentan para la pausa:

• ERROR_REQUEST_FORMATS
• ERROR_TASK_ABSENT
• ERROR_TASK_NOT_SUPPORTED
• ERROR_KEY_DOES_NOT_EXIST
• ERROR_KEY_EXPIRED
• ERROR_TASKID_INVALID
• ERROR_SETTLEMENT_FAILED
• ERROR_HIGH_DEMAND_DOMAIN
• ERROR_ZERO_CAPTCHA_FILESIZE
• ERROR_TOO_BIG_CAPTCHA_FILESIZE
• ERROR_IMAGE_TYPE_NOT_SUPPORTED
• ERROR_ILLEGAL_IMAGE

No cuenta el ERROR_THREADS_MAXIMUM devuelto por superar el límite de tareas simultáneas de la cuenta (con el campo limit); el error del mismo nombre devuelto cuando el servicio de reconocimiento está saturado (sin limit) sí cuenta. No cuentan los fallos de reconocimiento (ERROR_CAPTCHA_UNSOLVABLE), el saldo insuficiente (ERROR_ZERO_BALANCE), los campos que faltan (ERROR_REQUIRED_FIELDS), las preguntas no admitidas (ERROR_UNKNOWN_QUESTION), entre otros.

Durante la pausa:

• Solo se ven afectados createTask y getBalance, que devuelven ERROR_IP_BLOCKED_5MIN. getTaskResult no se ve afectado: las tareas creadas antes de la pausa se pueden consultar con normalidad.
• La respuesta incluye retryAfter (segundos restantes), blockReason (el código de error que provocó la pausa) y blockDetail (tipo, URL y sitekey de esas solicitudes); corrige tu programa según estos datos.
• Seguir enviando solicitudes no alarga la pausa. Termina automáticamente al vencer; no es necesario contactar con Soporte.
• En el Panel de yescaptcha.com puedes ver el registro de pausas de las últimas 24 horas.

{
  "errorId": 1,
  "errorCode": "ERROR_IP_BLOCKED_5MIN",
  "errorDescription": "...",
  "retryAfter": 182,
  "blockReason": "ERROR_TASK_NOT_SUPPORTED"
}

Caché de parámetros no válidos

Algunos errores dependen de los parámetros de la solicitud, y reenviar los mismos parámetros dará el mismo resultado:

• ERROR_RECAPTCHA_INVALID_SITEKEY
• ERROR_RECAPTCHA_INVALID_DOMAIN
• ERROR_INVALID_KEY_TYPE
• ERROR_DOMAIN_NOT_ALLOWED

Estos errores no cuentan para la pausa automática, sino que se guardan en caché en todo el sitio: tras la primera determinación se cachean 2 minutos, y si se vuelven a confirmar dentro de 1 hora, se cachean 10 minutos. Mientras dura la caché, las solicitudes idénticas (mismo tipo de tarea y websiteKey, o mismo dominio del sitio) devuelven directamente el error original, sin cobro de puntos, y la respuesta incluye "cached": true, retryAfter (segundos restantes de la caché) y badRequest (el parámetro coincidente). Al corregir el websiteKey o cambiar el tipo de tarea, el cambio surte efecto de inmediato.

Diferencias entre el límite de tareas simultáneas y la pausa automática

	Límite de tareas simultáneas	Pausa automática
Causa	Demasiadas tareas en proceso a la vez	Demasiadas solicitudes con error en poco tiempo
Comportamiento	Solo se rechaza la parte que excede el límite, con ERROR_THREADS_MAXIMUM	Se pausa la creación de tareas de este clientKey, con ERROR_IP_BLOCKED_5MIN
Recuperación	Puedes enviar nuevas en cuanto termine el procesamiento de otras; la reducción temporal a la mitad se restablece a los 10 minutos	Se restablece automáticamente al vencer
Cobro de puntos	No se cobra	No se cobra