API: códigos de erro

Formato padronizado e catálogo completo.

Formato

json

{
  "error": {
    "code": "validation_failed",
    "message": "Transição de status inválida: aceito → rascunho",
    "status": 422,
    "details": { "field": "status" }
  }
}

Catálogo

Código	HTTP	Significado
invalid_request	400	Payload malformado ou campo obrigatório ausente.
unauthorized	401	API key ausente ou inválida.
forbidden	403	Key não tem o escopo necessário.
freight_not_found	404	Frete não existe ou não pertence à empresa.
driver_not_found	404	Motorista não existe ou não pertence à empresa.
conflict	409	Recurso já existe (ex: code duplicado).
validation_failed	422	Falha em regra de negócio (transição inválida, etc.).
rate_limited	429	Limite de requisições excedido. Veja headers X-RateLimit-*.
internal_error	500	Erro interno. Tente novamente; persiste? Abra ticket.