Erros e idempotência

Separe falhas de configuração, resultados comerciais e indisponibilidade temporária. Repetir todas as respostas da mesma forma pode duplicar intenções ou esconder um erro permanente.

Classes de resposta

• 400 ou 422: payload inválido ou regra de validação não atendida. Corrija a requisição.
• 401: chave ausente, inválida, expirada ou revogada.
• 403: credencial reconhecida, mas sem permissão suficiente.
• 404: recurso inexistente no escopo de organização, ambiente e projeto da chave.
• 409: conflito de estado ou idempotência.
• 429: limite de requisições atingido; respeite o intervalo indicado e aplique backoff.
• 5xx: falha temporária ou interna; registre o request ID e reconcilie antes de repetir comandos.

Idempotência

Uma chave idempotente representa uma intenção, não uma tentativa de transporte. Gere a chave antes da primeira chamada e reutilize-a quando repetir o mesmo comando após timeout.

Não reutilize a chave para payloads diferentes e não gere outra chave apenas porque a resposta foi perdida.

Reconciliação

Quando não for possível saber se um comando foi concluído, consulte a emissão ou operação pelos identificadores disponíveis. Só repita depois de entender o estado atual.