Trate o status antes do corpo

StatusInterpretação e próximo passo
400Payload, UUID ou binding inválido; revise a requisição.
401Credencial ausente, inválida, revogada ou expirada.
403Organização, papel, vínculo ou política de acesso não permite a operação.
404Recurso não encontrado nesse contexto.
409Conflito de versão ou estado, nas operações que oferecem esse controle.
422Validação de negócio; revise os campos indicados.
429Limite de requisições atingido.
500 / 503Falha no serviço ou dependência; registre a correlação.

O middleware de negócio usa campos como error, statusCode e correlationId. Validações podem incluir details com propertyName e errorMessage. Autenticação, rate limiting e binding podem produzir outro formato ou um corpo vazio. Não dependa de um único schema para todos os erros.

Limite por token

A política pública usa uma janela fixa de um minuto, com padrão de 120 requisições por token, configurável pelo operador. O código não define uma fila de espera. O padrão não é uma promessa de quota igual em todos os ambientes.

Ao receber 429, reduza a taxa e espere a próxima janela. O contrato não garante o header Retry-After. Para leituras, use espera progressiva com variação; não repita uma criação de forma automática sem reconciliar seu resultado.

Correlação

O backend recebe ou gera X-Correlation-Id e o devolve na resposta. Inclua esse identificador ao investigar uma falha. Os endpoints públicos de criação não implementam um contrato genérico de Idempotency-Key.