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.
{
"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.