Idempotência e repetição de requisições

Uma falha de rede pode ocorrer depois de uma operação ter sido confirmada. O header Idempotency-Key ajuda a reconhecer repetições de certas mutações autenticadas, mas não funciona como garantia universal de execução única.

Uso básico

Crie uma chave única para a intenção de negócio, mantenha o mesmo corpo serializado e reutilize-a somente ao repetir essa tentativa.

POST /api/v1/debts
Authorization: Bearer CHAVE_DA_INTEGRACAO
Content-Type: application/json
Idempotency-Key: cadastro-titulo-123

Os corpos seguem o schema de criação da dívida. A chave não substitui referências externas nem a conciliação do resultado no sistema de origem.

O que entra na comparação

O middleware atua em POST, PATCH e DELETE, quando existe ator autenticado elegível. O hash considera método, caminho, query string, bytes do corpo e contexto de autorização. A resposta fica guardada por 24 horas, por organização, ator e chave. A mesma chave com uma solicitação diferente devolve 409 idempotency_conflict.

Se houver resposta armazenada compatível, o servidor devolve o corpo e status anteriores com X-Idempotency-Replay: 1. As condições atuais de acesso, como estado da credencial e MFA, são verificadas novamente antes da repetição.

Serializações diferentes de um JSON equivalente podem produzir hashes diferentes. O consumidor deve reutilizar os bytes da tentativa original.

Respostas que ficam fora

Rotas de autenticação, conta, chaves, webhooks e emissão de ticket de streaming ficam fora do armazenamento genérico. Respostas com cookies ou campos sensíveis, como tokens e URLs de upload, também não são persistidas pelo middleware. Rotas de produto podem recusar o header ou solicitar que a resposta não seja armazenada.

O armazenamento genérico considera respostas JSON entre 200 e 499 quando passam por essas restrições. Não presuma que uma resposta sem corpo, um upload ou uma operação Audience seja repetível por esse mecanismo.

Limites importantes

O fluxo consulta uma resposta anterior e a armazena após a execução. Ele não promete serializar duas primeiras tentativas concorrentes com a mesma chave. Portanto, mantenha as restrições de unicidade e os comandos de domínio como proteção para concorrência.

Em 409 concurrency_conflict, respeite Retry-After, releia o estado e decida se a ação ainda é válida. Em 503 unavailable, preserve a sessão e aguarde. Nunca gere uma nova intenção de negócio apenas porque a resposta demorou.

Consulte erros para o tratamento de falhas e envie o request_id ao suporte.