# Limite de tarefas simultâneas e pausa automática

> Limite de tarefas simultâneas do YesCaptcha (ERROR_THREADS_MAXIMUM, sem cobrança de pontos e sem contar para a pausa), pausa automática por excesso de erros (100 em um minuto pausam por 5 minutos, ERROR_IP_BLOCKED_5MIN) e cache de parâmetros inválidos (cached).

Source: https://docs.yescaptcha.com/pt/api/rate-limits/ · 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/rate-limits/

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](https://docs.yescaptcha.com/pt/help/contact.md). 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](https://docs.yescaptcha.com/pt/changelog.md).

```json
{
  "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

1.  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.
2.  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.
3.  Distribua as tarefas em lote de forma uniforme; não envie milhares de tarefas de uma só vez.

Exemplo em Python (asyncio):

```python
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:

-   [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_REQUEST_FORMATS)
-   [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASK_ABSENT)
-   [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
-   [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
-   [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED)
-   [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASKID_INVALID)
-   [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_SETTLEMENT_FAILED)
-   [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
-   [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
-   [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
-   [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
-   [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_ILLEGAL_IMAGE)

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](https://yescaptcha.com/) mostra o registro de pausas das últimas 24 horas.

```json
{
  "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:

-   [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
-   [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
-   [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_INVALID_KEY_TYPE)
-   [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)

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 |