Seção 09
Idempotência
Para repetir uma chamada com segurança (por exemplo, depois de um timeout) sem criar duas cobranças, envie o cabeçalho Idempotency-Key nas escritas (POST, PUT, PATCH, DELETE).
POST /payments
Idempotency-Key: pedido-1001-tentativa-1
| Regra | Detalhe |
|---|---|
| Formato da chave | De 1 a 255 caracteres entre letras, números, _, ., : e -. Fora disso: 400 |
| Escopo | A chave vale por estabelecimento |
| Mesma chave, mesma requisição | Devolve a resposta original, sem executar de novo (a resposta repetida traz o cabeçalho Idempotent-Replayed) |
| Mesma chave, requisição diferente | 422: Idempotency-Key já usada com outra requisição |
| Requisição original ainda em andamento | 409 com Retry-After: 5: aguarde e tente de novo |
| Resultado desconhecido (original sem resposta há mais de 10 min) | 409: consulte o recurso antes de tentar com outra chave |
Dica de implementação: derive a chave do seu próprio identificador (ex.: número do pedido). Assim, qualquer repetição do mesmo pedido reutiliza a mesma chave.
Importante: sem o cabeçalho, nenhuma proteção é aplicada. Uma repetição cria uma segunda cobrança.