Referência da API

Códigos de erro

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

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.

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

Como tratar os erros

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.
Falhas de reconhecimento e timeouts (ERROR_CAPTCHA_UNSOLVABLE, ERROR_TASK_TIMEOUT) podem ser tentados de novo criando uma nova tarefa.
Após um erro, pare de consultar esse taskId. Não reenvie a mesma requisição em alta frequência.
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.

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.