> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> O envelope de erro, todos os códigos que a API retorna e o que vale a pena repetir.

As falhas compartilham um único envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

`code` é estável e seguro para ramificações. `message` é para pessoas e pode mudar. `details` aparece quando
conseguimos apontar o campo com problema.

## Códigos

| Código | Status | Significado | Repetir? |
| - | - | - | - |
| `MISSING_API_KEY` | 401 | Token bearer ausente ou incorreto. | Não: corrija a chave |
| `VALIDATION_ERROR` | 400 | Corpo malformado, `taskType` desconhecido ou ausência de `payload.prompt` e `payload.query`. | Não: corrija a requisição |
| `REGION_UNSUPPORTED` | 422 | Este mecanismo nunca pode atender o `country` solicitado. | Não: escolha outro mecanismo ou região |
| `REGION_UNAVAILABLE` | 422 | No momento não há capacidade para o `country` solicitado neste mecanismo. | Mais tarde, quando a capacidade voltar |
| `RESOURCE_ALREADY_EXISTS` | 409 | `idempotencyKey` duplicado no endpoint individual. | Não: a tarefa já existe |
| `PAYLOAD_TOO_LARGE` | 413 | O corpo do lote passa de 8 MB. | Não: envie partes menores |
| `RESOURCE_NOT_FOUND` | 404 | Id de tarefa desconhecido, ou a tarefa passou da janela pública de polling de 24 horas. | Não |
| `ENQUEUE_ERROR` | — | Falha de um item dentro de um lote (por exemplo, um soluço de banco de dados em uma faixa). Aparece em `results[].error`, nunca como status HTTP. | Sim |

<Note>
  `400` é para uma requisição que não conseguimos interpretar nem entender. `422` é reservado para uma requisição
  perfeitamente formada que não conseguimos atender na região solicitada. Ramificar por `error.code` é mais durável
  do que pelo status.
</Note>

## Recusas por região

Os dois códigos de região são decididos **antes** de a tarefa entrar na fila, então você fica sabendo na hora, em vez
de ver uma tarefa gastar todas as tentativas e falhar com um erro que só mostra o sintoma.

`REGION_UNSUPPORTED` é permanente: esse mecanismo não pode atender o país solicitado.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

Veja [a tabela de combinações não atendidas](/pt/engines/capacity).

`REGION_UNAVAILABLE` é transitório: a rota existe, mas nada pode atendê-la neste momento. Consulte
[`GET /capacity`](/pt/api-reference/capacity) para ver o que cada região consegue atender agora.

## Falhas de lote são por item

Um lote bem formado sempre retorna `200`, mesmo que todas as tarefas dele falhem. O status HTTP descreve a
*requisição*; `results[].success` descreve cada *tarefa*.

```json theme={null}
{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}
```

Só uma requisição malformada como um todo (não é JSON, não é array, vazia, mais de 500 itens, mais de 8 MB ou não
autorizada) gera um 4xx para o próprio lote.

<Note>
  Um item do lote pode falhar com `REGION_UNAVAILABLE` ou `ENQUEUE_ERROR`, e nenhum dos dois consta no enum de erros
  por item do contrato de tarefas assíncronas que esta API implementa. Ambos são acréscimos, não substituições:
  `VALIDATION_ERROR` e `RESOURCE_ALREADY_EXISTS` não mudam.
</Note>

## Falhas no nível da tarefa

Uma tarefa que falha *depois* de entrar na fila não gera nenhum erro HTTP. Você descobre pelo status final:

```json theme={null}
{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}
```

Repare na diferença de formato: este `error` de nível superior é uma **string**, não o objeto
`{code, message, timestamp}` dos erros de requisição. Ele começa com um código seguido de uma frase fixa para esse
código, então decida pelo código: `ENGINE_TIMEOUT`, `ENGINE_NO_RESULT`, `ENGINE_FAILED`, ou `NO_IP_AVAILABLE` e
`NO_ACCOUNT_AVAILABLE` quando nenhuma capacidade ficou livre a tempo (tentar de novo mais tarde costuma funcionar).
`BAD_PAYLOAD` e `PAGE_UNAVAILABLE` (uma página do Naver que não pode ser lida de forma anônima) mantêm uma mensagem
que diz o que mudar. A mesma tarefa entrega um webhook com `task.status === "FAILED"`.