# Erros e retries

Identifique falhas de autenticação, validação, quota e disponibilidade.

## Ler uma resposta de erro

As falhas da API trazem uma mensagem e um código categórico. O requestId, quando informado, ajuda a localizar a requisição no suporte.


```json
{
  "error": {
    "code": "invalid_request",
    "message": "Evento inválido."
  },
  "requestId": "ID_DA_REQUISICAO"
}
```



## Como agir por status

A mensagem da resposta explica a regra específica que falhou.


| Status | Próximo passo |
| --- | --- |
| 400 / 422 | Confira campos, datas, URL, tipos e limites do contrato |
| 401 | Confira a credencial e sua validade |
| 403 | Confira escopos, acesso ao site e estado da conta/coleta |
| 402 | Confira saldo e direitos; não trate como confirmação de ingestão concluída |
| 404 | Confira rota, recurso e site autorizado |
| 409 | Confira o ID reutilizado e a compatibilidade do corpo com a operação anterior |
| 429 | Aguarde antes de repetir; há limite técnico ou operacional |
| 5xx / falha de rede | Use espera progressiva e preserve o ID lógico da operação |



## Quando repetir

Para timeout, falha de rede, 429 e erros transitórios de servidor, aguarde com backoff. Preserve o mesmo ID lógico e o mesmo conteúdo para a mesma ação. Erros de validação ou permissão pedem correção antes do retry.


- [Contrato de eventos](/api/events)
- [Contrato de receita](/api/revenue)