# Códigos de erro

> Todos os códigos de erro da API do YesCaptcha, com significado e como tratar cada um: formato da requisição, conta e saldo, tarefas simultâneas e pausa, resultado da tarefa, parâmetros do site, imagens, proxy e servidor. Requisições que retornam erro não são cobradas.

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

Quando ocorre um erro, a API retorna `errorId: 1`; `errorCode` é o código do erro e `errorDescription` é a descrição em texto. Requisições que retornam erro não cobram pontos: se o erro ocorre na criação da tarefa, nada é cobrado; se o reconhecimento falha ou expira depois da criação, há reembolso de pontos automático.

> **Dica:** No código, verifique `errorCode` e não o texto de `errorDescription`, que pode mudar.

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

## Como tratar os erros

1.  **Erros de parâmetros** (formato da requisição, clientKey, tipo de tarefa, parâmetros do site, imagens) não mudam ao reenviar; corrija a requisição primeiro.
2.  **Falhas de reconhecimento e timeouts** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) podem ser tentados de novo criando uma nova tarefa.
3.  Após um erro, **pare de consultar** esse `taskId`. Não reenvie a mesma requisição em alta frequência.
4.  Erros marcados como “conta para a pausa automática” fazem a criação de tarefas ser pausada por 5 minutos quando o mesmo `clientKey` acumula 100 deles em um minuto. Erros marcados como “em cache” não contam, mas, enquanto estiverem em cache, requisições idênticas recebem diretamente o mesmo erro. Veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).

## Todos os códigos de erro

### Formato da requisição

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Falta um campo obrigatório (como `clientKey`, ou `websiteURL` / `websiteKey` para o tipo de tarefa), ou o corpo da requisição não é JSON | Adicione os campos que faltam, listados na página do tipo de tarefa, e envie JSON com `POST` e `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Conta para a pausa automática) | O corpo da requisição não é um JSON válido | Gere o corpo com uma biblioteca de JSON em vez de concatenar strings; o JSON não pode conter comentários `//` |
| `ERROR_TASK_ABSENT` (Conta para a pausa automática) | O campo `task` está ausente em uma chamada a `createTask` | Coloque os parâmetros da tarefa em um objeto `task`. Com Python requests, use `json=data`, não `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Conta para a pausa automática) | `task.type` está escrito errado ou o tipo foi desativado | Copie o nome do tipo de "Tipos de tarefa e preços"; os nomes diferenciam maiúsculas de minúsculas |
| `ERROR_PAGE_NOT_FOUND` | O caminho solicitado não existe | Verifique a URL do endpoint, por exemplo `https://api.yescaptcha.com/createTask`; os nomes dos métodos diferenciam maiúsculas de minúsculas |
| `ERROR_BAD_REQUEST` | A requisição não pode ser processada, geralmente por causa de um método HTTP incorreto (GET em vez de POST) ou de valores de parâmetros inválidos | Envie JSON com `POST` e verifique os tipos e valores dos parâmetros |
| `ERROR_ILLEGAL_PARAMETERS` | O valor de um parâmetro é inválido. Típico da página de desafio do Cloudflare: `websiteURL` não é uma URL pública `http://` / `https://`, `postData` não é um objeto, ou `requiredCookies` não é um array de strings (retornado por createTask, sem cobrança de pontos); ou o domínio de destino não pôde ser resolvido pelo proxy (retornado por getTaskResult, com reembolso de pontos automático) | Corrija o valor conforme a tabela de parâmetros na página do tipo de tarefa. Se o domínio não pôde ser resolvido, verifique a grafia da URL e se o proxy consegue acessar o site |

### Conta e saldo

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Conta para a pausa automática) | A `clientKey` não existe: caracteres foram acrescentados ou perdidos ao copiar, ou a chave foi redefinida no Painel | Copie a chave novamente no Painel do yescaptcha.com, sem espaços nem quebras de linha |
| `ERROR_KEY_EXPIRED` (Conta para a pausa automática) | A `clientKey` expirou (retornado por createTask e getBalance, sem cobrança de pontos). Ou ela ficou sem uso por muito tempo e o sistema definiu um prazo de expiração para proteger a conta (um e-mail de aviso é enviado antes de expirar), ou o prazo de validade definido para esta `clientKey` já passou | Faça login no Painel do yescaptcha.com. Se a chave expirou por ficar muito tempo sem uso, gere uma nova `clientKey`; o saldo é transferido automaticamente para a nova. Se foi definido um prazo de validade, altere-o ou use outra `clientKey`. Depois, atualize seu programa com a nova `clientKey` |
| `ERROR_KEY_IP_NOT_ALLOWED` | Esta `clientKey` tem uma lista de IPs permitidos e o IP de origem da requisição não está nela (retornado por createTask e getBalance, sem cobrança de pontos, não conta para a pausa automática) | Faça login no Painel do yescaptcha.com e adicione o IP público da máquina que envia as requisições à lista de IPs permitidos desta `clientKey`, ou use outra `clientKey`. Se várias máquinas chamam a API, adicione o IP público de cada uma (trata-se do IP que chama a API do YesCaptcha, não do proxy nos parâmetros da tarefa) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Esta `clientKey` tem um limite de consumo e o que resta dele no período atual é menor que o custo desta tarefa (retornado por createTask, sem cobrança de pontos, não conta para a pausa automática). O limite considera os pontos efetivamente cobrados; os pontos com reembolso de pontos por tarefas que falharam ou expiraram voltam para o limite | Faça login no Painel do yescaptcha.com e aumente o limite desta `clientKey`, aguarde o próximo período (o limite é zerado todos os dias, toda segunda-feira ou no dia 1 de cada mês, no horário de Pequim; um limite único não é zerado), ou use outra `clientKey`. `getBalance` retorna o limite restante desta `clientKey` (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Saldo insuficiente. O saldo deve ser maior que 10 pontos para criar uma tarefa | Faça uma recarga e tente novamente. Use `getBalance` para consultar o saldo |

### Simultaneidade e pausas

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Às vezes conta para a pausa automática) | Há tarefas simultâneas demais deste tipo em andamento na conta. `limit` na resposta é o limite de tarefas simultâneas atual. A requisição não foi processada e não houve cobrança de pontos | Aguarde as requisições em andamento retornarem, ou espere 1–2 segundos e tente novamente; limite o número de requisições aguardando resultado ao mesmo tempo |
| `ERROR_IP_BLOCKED_5MIN` | Esta `clientKey` gerou erros demais em pouco tempo e sofreu pausa automática. `retryAfter` é o número de segundos restantes e `blockReason` é o erro que causou a pausa | Corrija a requisição de acordo com `blockReason` e aguarde `retryAfter` segundos; enviar requisições durante a pausa não a prolonga |
| `ERROR_NO_SLOT_AVAILABLE` | O serviço de reconhecimento está temporariamente sobrecarregado. Quando retornado por createTask, nenhum ponto é cobrado; uma tarefa que ficou na fila por tempo demais também retorna esse erro em getTaskResult, e os pontos são reembolsados automaticamente | Aguarde alguns segundos e crie a tarefa novamente |

### Tarefas e resultados

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Conta para a pausa automática) | O `taskId` não existe, expirou (os resultados são mantidos por cerca de 10 minutos), pertence a outra `clientKey` ou foi criado no outro endpoint | Pare de consultar periodicamente esta tarefa. Consulte usando o mesmo endpoint e a mesma `clientKey` que a criaram |
| `ERROR_TASK_TIMEOUT` | A tarefa não foi concluída dentro do tempo limite (geralmente 110 segundos); o reembolso de pontos foi feito automaticamente | Crie uma nova tarefa; se o timeout persistir, tente outro tipo de tarefa para o mesmo captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Não foi possível resolver o captcha desta vez; o reembolso de pontos foi feito. Isso não conta para a pausa automática | Crie uma nova tarefa. Se continuar falhando, verifique `websiteURL`, `websiteKey` e os demais parâmetros, ou tente outro tipo de tarefa para o mesmo captcha |
| `ERROR_SETTLEMENT_FAILED` (Conta para a pausa automática) | O saldo era insuficiente no momento da liquidação, então nenhum resultado foi retornado | Faça uma recarga e crie uma nova tarefa |
| `ERROR_NO_SUCH_CAPCHA_ID` | A tarefa não é mais válida | Pare de consultar periodicamente esta tarefa e crie uma nova |
| `ERROR_RECAPTCHA_TIMEOUT` | O reconhecimento do captcha excedeu o tempo limite; o reembolso de pontos foi feito | Crie uma nova tarefa |

### Parâmetros do site de destino

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Em cache, não conta para a pausa) | A `websiteKey` é inválida | Encontre a sitekey na página novamente (veja os guias de como encontrar parâmetros). Requisições idênticas retornam este erro diretamente durante o período de cache, com `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Em cache, não conta para a pausa) | O domínio de `websiteURL` não corresponde à `websiteKey` | Defina `websiteURL` como o endereço da página que exibe o captcha |
| `ERROR_INVALID_KEY_TYPE` (Em cache, não conta para a pausa) | A sitekey pertence a outro tipo de captcha, por exemplo, uma chave v3 usada com um tipo de tarefa v2 | Primeiro identifique o tipo de captcha (veja "Identificar o tipo de captcha") e escolha o tipo de tarefa correspondente; para o v2 invisível, defina `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Em cache, não conta para a pausa) | Este site não é suportado | Tente outro tipo de tarefa para o mesmo captcha ou entre em contato com o suporte |
| `ERROR_HIGH_DEMAND_DOMAIN` (Conta para a pausa automática) | Este site não é suportado | Pare de enviar tarefas para este site e entre em contato com o suporte |
| `ERROR_FAILED_LOADING_WIDGET` | Não foi possível carregar o captcha com os parâmetros informados | Verifique `websiteURL` e `websiteKey`; para tipos de tarefa com proxy próprio, verifique se o proxy consegue acessar o site |

### Imagens

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Conta para a pausa automática) | A imagem está vazia ou é pequena demais | Verifique se os dados em Base64 estão completos e sem o prefixo `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Conta para a pausa automática) | A imagem é grande demais | Comprima ou redimensione a imagem; o corpo da requisição inteira deve ficar abaixo de 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Conta para a pausa automática) | O formato da imagem não é suportado, ou a imagem não é uma que este tipo de tarefa consiga processar. Uma única ocorrência pausa a chave por 30 minutos | Use JPG ou PNG e confirme que a imagem corresponde ao tipo de tarefa, por exemplo, o reconhecimento de imagem do reCAPTCHA exige 100x100, 300x300 ou 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Conta para a pausa automática) | O tamanho da imagem não atende aos requisitos deste tipo de tarefa | Redimensione a imagem conforme descrito na página do tipo de tarefa |
| `ERROR_PARSE_IMAGE_FAIL` | Não foi possível decodificar a imagem, geralmente porque o Base64 está truncado ou tem um prefixo | Verifique a codificação Base64 e remova o prefixo `data:` e as quebras de linha |
| `ERROR_UNKNOWN_QUESTION` | A `question` está errada, ou esta pergunta ainda não é suportada | Compare com a lista de perguntas na página do tipo de tarefa. Para perguntas não suportadas, entre em contato com o suporte; novas perguntas geralmente são suportadas em até 3 dias úteis |
| `ERROR_UNKNOW_450x450_QUESTION` | Esta pergunta ainda não é suportada para imagens 4x4 (450x450) | Recarregue o desafio na página para obter outra pergunta |

### Proxies

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | O proxy recusou a conexão | Verifique o endereço, a porta e o protocolo do proxy, e confirme que ele aceita conexões externas (não pode ser um endereço local como 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | A conexão com o proxy excedeu o tempo limite | Use um proxy mais estável |
| `ERROR_PROXY_READ_TIMEOUT` | A leitura de dados pelo proxy excedeu o tempo limite | Use um proxy mais rápido |
| `ERROR_PROXY_BANNED` | O proxy está indisponível, ou o IP dele está bloqueado pelo site de destino | Use outro proxy |
| `ERROR_PROXY_INCORRECT` | Os parâmetros do proxy estão mal formatados | Verifique o formato de `proxyType`, `proxyAddress`, `proxyPort` (ou da string `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | O proxy é transparente e expõe o IP real | Use um proxy anônimo (de alto anonimato) |
| `ERROR_PROXY_NOT_AUTHORISED` | O usuário ou a senha do proxy estão incorretos | Verifique `proxyLogin` e `proxyPassword` (ou as credenciais na string `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | O handshake TLS com o proxy falhou, geralmente porque `proxyType` está errado (por exemplo, https definido para um proxy http) | Verifique o protocolo do proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Não foi possível conectar ao servidor proxy | Verifique o endereço e a porta do proxy e confirme que o proxy está funcionando |

### Servidor

| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | O serviço está temporariamente indisponível (o código é escrito `UNAVALIABLE`) | Tente novamente mais tarde; entre em contato com o suporte se persistir |
| `ERROR_INTERNAL_SERVER_ERROR` | Ocorreu um erro interno no servidor | Tente novamente mais tarde; se persistir, entre em contato com o suporte e informe o `taskId` |
| `ERROR_UNKNOWN` | Um erro não classificado | Tente novamente mais tarde; se persistir, entre em contato com o suporte e informe o `taskId` |

## Campos adicionais

Algumas respostas de erro trazem campos extras:

| Campo | Aparece em | Descrição |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, erros em cache | Quantos segundos ainda faltam para tentar de novo |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Código de erro que causou a pausa |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Tipo, URL e sitekey das requisições que causaram a pausa, para facilitar a localização |
| `cached` | Erros em cache | `true` indica que o resultado veio do cache e nada foi reconhecido |
| `badRequest` | Erros em cache | Parâmetros que atingiram o cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Seu limite atual de tarefas simultâneas |

As regras de idioma de `errorDescription` estão em [Requisição e resposta](https://docs.yescaptcha.com/pt/api/overview.md).