Referência da API

Limite de tarefas simultâneas e pausa automática

Esta página foi traduzida automaticamente da versão em chinês e pode conter erros. Prevalece a versão em chinês.

Para manter o reconhecimento rápido para todos os usuários, o YesCaptcha tem três regras de proteção: um limite de tarefas em processamento ao mesmo tempo por conta (limite de tarefas simultâneas); uma pausa de alguns minutos para o clientKey que gera erros demais em pouco tempo (pausa automática); e um cache de parâmetros já considerados inválidos, que devolve o erro original por um período. Em nenhum desses casos há cobrança de pontos.

Limite de tarefas simultâneas

Limitamos, por conta e por tipo de tarefa, o número de tarefas em processamento no mesmo instante. O limite é de simultaneidade, não de requisições por minuto.

A tarefa conta como “em processamento” desde a chamada a createTask até o retorno dessa chamada. Os tipos de reconhecimento de imagem devolvem o resultado diretamente em createTask, então simultaneidade ≈ tarefas enviadas por segundo × tempo de cada tarefa. Por exemplo, com 0.5 segundo por tarefa e 40 tarefas por segundo, a simultaneidade é de cerca de 20.
As requisições da mesma conta são somadas; cada tipo de tarefa é contado separadamente.
Requisições acima do limite retornam ERROR_THREADS_MAXIMUM imediatamente, e limit na resposta indica o seu limite atual. Não há cobrança de pontos, e elas não contam para a pausa automática.
Quando os servidores de reconhecimento ficam sobrecarregados, a conta que mais ocupa tempo de reconhecimento tem o limite desse tipo de tarefa reduzido pela metade temporariamente, com restauração automática após 10 minutos. Isso só reduz a velocidade; a conta não é pausada.
Se precisar de um limite maior, fale com o suporte. Quando os limites padrão de cada tipo forem definidos, eles serão publicados nesta página e no Registro de atualizações do serviço.

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

(Os números do exemplo são apenas ilustrativos.)

Boas práticas

Limite no programa o “número de requisições aguardando resultado ao mesmo tempo”, por exemplo com um semáforo (Semaphore) ou um pool de threads de tamanho fixo, em vez de controlar apenas quantas são enviadas por segundo.
Ao receber ERROR_THREADS_MAXIMUM, espere as requisições já enviadas retornarem antes de enviar novas, ou aguarde 1 a 2 segundos e tente de novo. Não repita em loop imediato.
Distribua as tarefas em lote de forma uniforme; não envie milhares de tarefas de uma só vez.

Exemplo em 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

Quando o mesmo clientKey gera muitas requisições com erro em pouco tempo, a criação de tarefas é pausada automaticamente:

Condição	Duração da pausa
100 ocorrências dos erros listados abaixo no mesmo minuto do calendário	5 minutos
1 ocorrência de `ERROR_IMAGE_TYPE_NOT_SUPPORTED`	30 minutos
1000 acertos no “cache de parâmetros inválidos” no mesmo minuto do calendário	5 minutos

Erros que contam para a pausa:

O ERROR_THREADS_MAXIMUM retornado pelo excesso de simultaneidade da conta (com o campo limit) não conta; o erro de mesmo nome retornado quando o serviço de reconhecimento está ocupado (sem limit) conta. Falha de reconhecimento (ERROR_CAPTCHA_UNSOLVABLE), saldo insuficiente (ERROR_ZERO_BALANCE), campos ausentes (ERROR_REQUIRED_FIELDS), pergunta não suportada (ERROR_UNKNOWN_QUESTION) e similares não contam.

Durante a pausa:

Só createTask e getBalance são afetados e retornam ERROR_IP_BLOCKED_5MIN. getTaskResult não é afetado: as tarefas criadas antes da pausa continuam podendo ter o resultado consultado normalmente.
A resposta traz retryAfter (quantos segundos faltam), blockReason (o código de erro que causou a pausa) e blockDetail (tipo, URL e sitekey dessas requisições); use-os para corrigir o programa.
Continuar enviando requisições não prolonga a pausa. Ela termina automaticamente no prazo, sem precisar falar com o suporte.
O painel em yescaptcha.com mostra o registro de pausas das últimas 24 horas.

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

Cache de parâmetros inválidos

Alguns erros dependem dos parâmetros da requisição, e reenviar os mesmos parâmetros não muda o resultado:

Esses erros não contam para a pausa automática; em vez disso, ficam em cache em todo o site: 2 minutos após a primeira verificação e 10 minutos se forem confirmados novamente dentro de 1 hora. Durante o cache, requisições idênticas (mesmo tipo de tarefa e websiteKey, ou mesmo domínio do site) retornam diretamente o erro original, sem cobrança de pontos, com "cached": true, retryAfter (segundos restantes do cache) e badRequest (os parâmetros que coincidiram). Corrigir o websiteKey ou trocar o tipo de tarefa tem efeito imediato.

Diferença entre o limite de tarefas simultâneas e a pausa automática

	Limite de tarefas simultâneas	Pausa automática
Causa	Tarefas demais em processamento ao mesmo tempo	Requisições com erro demais em pouco tempo
Efeito	Só as requisições excedentes são recusadas, com `ERROR_THREADS_MAXIMUM`	Este `clientKey` fica sem poder criar tarefas, com `ERROR_IP_BLOCKED_5MIN`
Recuperação	Assim que alguma requisição termina, já dá para enviar outra; a redução pela metade é restaurada após 10 minutos	Termina automaticamente no prazo
Cobrança de pontos	Não	Não