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

# Códigos de erro e limites

> Respostas de erro da API e boas práticas

## Formato de erro

Em erros tratados pela plataforma, a resposta costuma ser um JSON:

```json theme={null}
{
  "error": "CODIGO",
  "message": "Mensagem legível"
}
```

## Códigos frequentes

| HTTP | `error` (exemplos)     | Quando ocorre                                                                          |
| ---- | ---------------------- | -------------------------------------------------------------------------------------- |
| 400  | `VALIDATION_ERROR`     | Corpo JSON inválido ou fora do schema (ex.: campo obrigatório ausente, tipo incorreto) |
| 401  | `UNAUTHORIZED`         | API Key inválida ou ausente                                                            |
| 402  | `INSUFFICIENT_CREDITS` | Saldo insuficiente para a consulta                                                     |
| 404  | `PRODUCT_NOT_FOUND`    | Produto inativo, slug inexistente ou sem preço para o plano                            |
| 502  | `PROVIDER_ERROR`       | Falha ao falar com o fornecedor externo                                                |
| 500  | `INTERNAL_ERROR`       | Erro interno não esperado                                                              |

## Limites e desempenho

* O corpo da consulta aceita `document` com tamanho limitado (até **100 caracteres** no contrato atual).
* **Timeout** e **rate limiting** podem ser aplicados por fornecedor ou pela infraestrutura — consulte o contrato.
* Use **retry com backoff** apenas para erros **transientes** (5xx); evite repetir 400/401/402/404 sem corrigir a causa.

## Health check

`GET /health` retorna status dos serviços internos (**database**, **auxiliary**). Útil para monitoramento; não substitui o contrato de SLA comercial.