Pular para o conteúdo principal
Um sistema que perde a resposta por timeout costuma reenviar a requisição. Sem proteção, um POST repetido cria um item duplicado ou dispara o mesmo alerta duas vezes, cobrando duas vezes. O header Idempotency-Key resolve isso.

​
Onde usar

Em duas rotas, e só nelas:
  • POST /establishments/{establishment}/items
  • POST /establishments/{establishment}/items/{item}/events
O header é opcional, mas recomendamos enviá-lo sempre nas duas.

​
Como usar

Gere um valor único para cada operação que você pretende fazer (um UUID v4 serve) e envie-o em Idempotency-Key. O valor tem de 1 a 255 caracteres ASCII visíveis. Em caso de falha de rede, repita a requisição com a mesma chave e o mesmo corpo.

​
O que acontece

  • A primeira resposta fica guardada por 24 horas: tanto um sucesso (2xx) quanto uma recusa de regra, isto é, qualquer erro com code próprio, como insufficient_credits, dispatch_in_progress ou dispatch_too_soon.
  • Uma repetição com a mesma chave e o mesmo corpo recebe a resposta guardada, byte a byte, com o header Idempotent-Replayed: true e o Content-Language original. Nada é processado de novo e nada é cobrado de novo.
  • Uma recusa guardada não é tentada de novo. Para tentar de verdade (por exemplo, depois de comprar créditos), envie uma chave nova.
  • validation_failed, forbidden e erros de servidor (5xx) não são guardados: corrija e repita, com a mesma chave se quiser.
  • A repetição conta no limite de requisições (veja Convenções).
Guardar também as recusas de regra é diferente do que fazem algumas APIs de pagamento, que só guardam sucessos. Aqui, uma recusa como dispatch_too_soon repetida com a mesma chave continua recusada mesmo depois que os segundos passaram: use uma chave nova.

​
Erros do próprio header