# Códigos de erro



## Resposta de sucesso

```json
{
  "success": true,
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {},
  "meta": {}
}
```

| Campo      | Descrição                                        |
| ---------- | ------------------------------------------------ |
| `success`  | `true` em respostas OK                           |
| `trace_id` | ID de correlação (também no header `X-Trace-Id`) |
| `data`     | Recurso ou resultado                             |
| `meta`     | Opcional — custo (`meta.cost`), paginação etc.   |

Com `X-Include-Cost: true` ou em dry-run, `meta` traz o custo da operação — veja os formatos em [Dry-run](/cobranca-e-limites#dry-run). Listagens trazem a paginação dentro de `data` (`total` e, no PDF, `page` e `page_size`), não em `meta`.

## Formato de erro

```json
{
  "success": false,
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "billing.insufficient_credits",
    "message": "Créditos insuficientes para esta operação.",
    "details": { "required": 100, "available": 50 }
  }
}
```

| Campo           | Descrição                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `error.code`    | Identificador estável — trate erros por ele, nunca pela `message`                               |
| `error.message` | Texto legível; pode mudar entre versões                                                         |
| `error.details` | Contexto estruturado opcional; em `validation.failed`, `details.fields` traz os erros por campo |
| `trace_id`      | Informe em tickets de suporte                                                                   |

## Erros comuns a todas as ferramentas

### Autenticação e permissões

<ErrorTable group="auth" />

### Créditos e conta

<ErrorTable group="billing" />

### Requisição e limites

<ErrorTable group="request" />

### Agentes de IA (MCP)

<ErrorTable group="agents" />

### Plataforma

<ErrorTable group="platform" />

### Vídeo

<ErrorTable group="video" />

## Erros por ferramenta

<ToolErrorSections />

Jobs assíncronos (PDF) também expõem `error_code` no próprio recurso quando `status` é `failed`; códigos marcados como **assíncrono** aparecem apenas ali.

## Boas práticas

1. Trate `402` com um fluxo de recarga no seu sistema.
2. Em `429`, respeite `X-RateLimit-Reset` antes de tentar de novo.
3. Use `X-Dry-Run` para capturar `validation.failed` sem custo.
4. Repita apenas erros `5xx` e de rede, sempre com a mesma `X-Idempotency-Key`.
5. Registre o `trace_id` de toda resposta com erro.