# Erros e limites

## Formato dos erros

Todos os erros da API seguem o mesmo formato:

```json
{ "code": "NOT_FOUND", "message": "CNPJ não encontrado.", "requestId": "9f2c..." }
```

**Trate pelo `code`, não pela mensagem.** Os textos podem mudar, os códigos não. Guarde o `requestId` no seu log: é por ele que o suporte localiza a chamada.

- Quando a chamada é recusada antes de chegar à consulta (`401` e `429`), o `requestId` pode vir `null` e o cabeçalho `X-Request-Id` pode não vir.
- Um erro gerado fora da API, na sua rede ou num proxy, pode chegar sem corpo JSON. Um cliente robusto confere o status HTTP e o `Content-Type` antes de ler o corpo.

## Códigos

| HTTP | `code` | O que fazer |
|---|---|---|
| 400 | `INVALID_CNPJ` | Formato ou dígito verificador inválido. Confira antes de reenviar |
| 401 | `API_KEY_INVALID` | Chave ausente, inválida, revogada ou expirada. Não repita a chamada |
| 403 | `INSUFFICIENT_BALANCE` | Sem saldo e sem franquia disponível. Recarregue a carteira no app |
| 404 | `NOT_FOUND` | CNPJ não encontrado na base |
| 408 | `CNPJ_LOOKUP_TIMEOUT` | A consulta demorou demais. Pode repetir |
| 429 | `RATE_LIMITED` | Reduza o ritmo. Respeite o cabeçalho `Retry-After` |
| 500 | `INTERNAL_ERROR` | Erro inesperado. Repita com espera crescente e, se persistir, fale com o suporte informando o `requestId` |
| 503 | `CNPJ_SOURCE_UNAVAILABLE` | Base indisponível no momento. Pode repetir |
| 503 | `SERVICE_UNAVAILABLE` | A API está fora do ar ou reiniciando (resposta da borda). Pode repetir |

Um caminho que não existe sob `/v1` responde HTTP `404` sem o campo `code`.

## Quando repetir

Em `408`, `429`, `500` e `503`, repita a chamada com espera crescente (*backoff*). Nos demais códigos, repetir devolve o mesmo erro.

Repetir é seguro: a mesma consulta dentro de 24 horas não é cobrada de novo. Veja [Preços e cobrança](https://toreva.com.br/developers/precos-e-cobranca).

## Limites

| Limite | Valor |
|---|---|
| Por chave | 10 requisições por segundo |
| Por IP | 20 requisições por segundo, com pico de 40 |

Acima do limite, a API responde `429 RATE_LIMITED`.

## Cabeçalhos da resposta

| Cabeçalho | Conteúdo |
|---|---|
| `X-Request-Id` | Identificador da chamada, para o suporte |
| `X-Toreva-Charged` | `true` quando a consulta contou como consulta cobrável, seja debitada do saldo, seja coberta pela franquia do mês; `false` quando o mesmo CNPJ é reconsultado dentro de 24 horas |
| `X-Toreva-Balance-Cents` | Saldo restante da carteira, em centavos. Vem nas respostas `200` |