Idempotência e versões

Idempotência nos POSTs

Todo POST exige Idempotency-Key de 8 a 128 caracteres, único por operação lógica. Reutilize a mesma chave e o mesmo corpo após timeout ou falha de rede. O resultado fica reservado por 7 dias; uma repetição concluída recebe Idempotency-Replayed: true. A mesma chave com caminho ou corpo diferente retorna 409.

Se houver interrupção depois da execução e antes do armazenamento da resposta, a reserva permanece pendente. Nesse caso, o servidor retorna 409 e não executa novamente. Confira o estado do cartão antes de iniciar outra operação com uma chave nova.

Versão em edições e movimentos

PATCH de cartão e POST de movimentação exigem version ou If-Match: "v1". Sem versão: 428. Versão antiga: 409 com code: version_conflict. Consulte o cartão novamente, concilie a alteração e tente com a versão atual; para um novo POST, use uma nova chave de idempotência.