# Erros

A API Auvo segue códigos HTTP padrão e retorna um payload `{ "error": "<mensagem>" }`.

## Mapa rápido

| Código | Significado | O que fazer |
|  --- | --- | --- |
| 400 | Payload inválido | Revise schema/tipos antes de reenviar. |
| 401 | Token ausente/expirado | Renovar com `POST /login`. |
| 403 | Rate limit excedido | Aplicar backoff exponencial. |
| 404 | Recurso inexistente | Confirmar `id`/slug. |
| 409 | Conflito (ex.: duplicidade) | Verificar estado remoto antes. |
| 415 | `Content-Type` faltando em POST | Enviar `application/json`. |
| 422 | Validação semântica | Ler `error` e corrigir. |
| 429 | Rate limit (reserva futura) | Tratar igual a 403. |
| 500 | Falha interna | Reportar em help@auvo.com.br com `deliveryId`/timestamp. |


## Envelope


```json
{ "error": "The field 'email' is not a valid email address" }
```

## Estratégia de retry

- **Idempotentes (`GET`, `PUT`, `DELETE`)**: retry com backoff em 5xx e 403.
- **Não idempotentes (`POST`, `PATCH`)**: evite retry cego — use correlação
(ex.: `externalId`) para detectar duplicatas antes de reenviar.


## Troubleshooting

1. Guarde `X-Request-Id` (quando presente) em logs.
2. Reproduza em curl antes de reportar — remove incerteza de cliente HTTP.
3. Se possível, envie payload redigido ao abrir ticket.