Tratamento de Erros
A API usa códigos de resposta HTTP convencionais para indicar o sucesso ou falha das solicitações. Esta página documenta formatos de erro e estratégias de tratamento.
Formato de Resposta de Erro
Todas as respostas de erro seguem uma estrutura JSON consistente:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Campo | Descrição |
|---|---|
| error | Código de erro legível por máquina |
| message | Descrição do erro legível por humanos |
| timestamp | Quando o erro ocorreu |
| path | O caminho do endpoint solicitado |
| details | Detalhes adicionais para erros de validação (opcional) |
Códigos de Status HTTP
| Código | Descrição |
|---|---|
| 400 | Parâmetros de solicitação inválidos ou corpo da solicitação malformado |
| 401 | Chave de API ausente ou inválida |
| 403 | Chave de API não tem as permissões necessárias para este endpoint |
| 404 | Recurso solicitado não existe |
| 429 | Limite de taxa excedido - tente novamente após o tempo especificado |
| 500 | Erro interno do servidor - contate o suporte se persistir |
| 503 | Serviço temporariamente indisponível - tente novamente mais tarde |
Estratégia de Tentativa
Para erros transitórios, implemente uma estratégia de tentativa com backoff exponencial:
- Para erros 429, aguarde o tempo especificado no cabeçalho X-RateLimit-Reset antes de tentar novamente
- Para erros 5xx, use backoff exponencial (1s, 2s, 4s, 8s...) com variação
- Defina uma contagem máxima de tentativas (ex: 3-5 tentativas) para evitar loops infinitos
Limitação de Taxa
Quando você excede o limite de taxa, a API retorna um código de status 429 com detalhes sobre quando você pode tentar novamente:
Use o campo retryAfter ou o cabeçalho X-RateLimit-Reset para determinar quando tentar novamente sua solicitação.
Erros de Validação
Para erros 400, a resposta inclui um array de detalhes com erros específicos por campo:
Melhores Práticas de Tratamento de Erros
- Sempre verifique o código de status HTTP antes de processar o corpo da resposta
- Implemente backoff exponencial para erros 429 e 5xx
- Registre erros com timestamp e caminho para depuração
- Trate códigos de erro específicos de forma diferente (ex: 401 aciona re-autenticação)