# Requisições e respostas

> Convenções gerais da API do YesCaptcha: POST com JSON, autenticação por clientKey, formato de resposta com errorId, tarefas síncronas e assíncronas, consulta a cada 5 segundos, timeout de 110 segundos, resultado guardado por cerca de 10 minutos, idioma das mensagens conforme Accept-Language.

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

Todos os métodos usam `POST` por HTTPS com um corpo JSON (só `/useragent` é `GET`), autenticam com o `clientKey` no corpo da requisição e respondem em JSON: `errorId` igual a 0 indica sucesso; igual a 1 indica falha, acompanhada de `errorCode`. Resolver um captcha tem dois passos: `createTask` cria a tarefa e `getTaskResult` é consultado a cada 5 segundos para obter o resultado. Os tipos síncronos devolvem o resultado diretamente em `createTask`.

## Requisição

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```

-   Endpoint: `https://api.yescaptcha.com` (global) ou `https://cn.yescaptcha.com` (China). Veja [Endereços de acesso](https://docs.yescaptcha.com/pt/getting-started/endpoints.md).
-   O corpo é JSON, enviado com o cabeçalho `Content-Type: application/json`, com no máximo 6 MB. O JSON não pode conter comentários.
-   Toda requisição deve incluir `clientKey`, copiado por inteiro do Painel.

> **Cuidado:** Com o requests do Python, use `json=data` e não `data=data`. O segundo envia um formulário e retorna `ERROR_TASK_ABSENT` ou `ERROR_REQUIRED_FIELDS`.

## Resposta

Sucesso:

```json
{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```

Falha:

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

| Campo | Descrição |
| --- | --- |
| `errorId` | 0 sucesso, 1 falha |
| `errorCode` | Código de erro em caso de falha; significado e como resolver em [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md) |
| `errorDescription` | Descrição textual do motivo da falha |
| `taskId` | ID da tarefa |
| `status` | `processing` (em processamento) ou `ready` (concluída) |
| `solution` | Resultado do reconhecimento; os campos variam conforme o tipo de tarefa, veja a página de cada tipo |

Para avaliar o resultado, use `errorId` e `errorCode`. Não analise o texto de `errorDescription`, que pode mudar.

## Síncrono e assíncrono

|  | Assíncrono | Síncrono |
| --- | --- | --- |
| Quais tipos | Tipos que retornam token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), página de desafio do Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Reconhecimento de imagem (nomes terminados em `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` retorna | `taskId` | `status: "ready"` e `solution` |
| Como obter o resultado | Chamar `getTaskResult` a cada 5 segundos | Nada mais a fazer |

Para saber a qual grupo cada tipo pertence, veja a coluna “Modo de retorno” em [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).

## Consulta periódica

1.  Depois que `createTask` retornar o `taskId`, aguarde 5 segundos e chame `getTaskResult`.
2.  Se retornar `status: "processing"`, aguarde mais 5 segundos e tente de novo; se retornar `status: "ready"`, o resultado está em `solution`.
3.  Se retornar `errorId: 1`, pare de consultar essa tarefa e trate o `errorCode`.

-   Consultas repetidas do mesmo `taskId` em menos de 5 segundos retornam `processing` imediatamente; consultar com mais frequência não faz o resultado chegar mais rápido.
-   Uma tarefa é processada por no máximo 110 segundos, em geral (alguns tipos levam de 180 a 220 segundos). Passado esse tempo, retorna `ERROR_TASK_TIMEOUT` e há reembolso de pontos automático.
-   O resultado fica guardado no servidor por cerca de 10 minutos; depois disso o `taskId` expira e a consulta retorna `ERROR_TASKID_INVALID`.
-   Consultar o resultado não cobra pontos; a cobrança de pontos ocorre apenas na criação da tarefa.

## Idioma das mensagens

Nas mensagens de pausa automática, de cache de parâmetros inválidos e de parada de consulta, o `errorDescription` segue o cabeçalho `Accept-Language`: se começar com `zh`, vem em chinês; para os demais idiomas, em inglês; sem o cabeçalho, vêm os dois idiomas. As descrições dos outros códigos de erro não são afetadas.

## Próximos passos

-   [createTask: criar tarefa](https://docs.yescaptcha.com/pt/api/create-task.md)
-   [getTaskResult: obter resultado](https://docs.yescaptcha.com/pt/api/get-task-result.md)
-   [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md): erros em excesso causam uma pausa de alguns minutos