Tratamento de erros

A API utiliza códigos de resposta HTTP convencionais para indicar o êxito ou a falha dos pedidos. Esta página documenta formatos de erro e estratégias de tratamento.

Formato da 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 Estado HTTP

Código	Descrição
400	Parâmetros do pedido inválidos ou corpo do pedido malformado
401	Chave de API em falta ou inválida
403	A chave de API não tem as permissões necessárias para este endpoint
404	O recurso pedido não existe
429	Limite de pedidos excedido - tente novamente após o tempo especificado
500	Erro interno do servidor - contacte o suporte se persistir
503	Serviço temporariamente indisponível - tente novamente mais tarde

Estratégia de Nova Tentativa

Para erros transitórios, implemente uma estratégia de nova tentativa com recuo exponencial:

Para erros 429, aguarde pelo tempo especificado no cabeçalho X-RateLimit-Reset antes de tentar novamente
Para erros 5xx, utilize recuo exponencial (1s, 2s, 4s, 8s...) com jitter
Defina um número máximo de tentativas (por ex., 3-5 tentativas) para evitar ciclos infinitos

Limitação de Pedidos

Quando excede o limite de pedidos, a API devolve um código de estado 429 com detalhes sobre quando pode tentar novamente:

Utilize o campo retryAfter ou o cabeçalho X-RateLimit-Reset para determinar quando deve tentar novamente o seu pedido.

Erros de Validação

Para erros 400, a resposta inclui um array details com erros específicos ao nível do campo:

Boas Práticas de Tratamento de Erros

Verifique sempre o código de estado HTTP antes de analisar o corpo da resposta
Implemente recuo exponencial para erros 429 e 5xx
Registe os erros com o carimbo de data/hora e o caminho para depuração
Trate códigos de erro específicos de forma diferente (por exemplo, o 401 aciona a reautenticação)