Skip to main content
Envie Idempotency-Key em todo POST. A conexão que cai depois da requisição e antes da resposta deixa você sem saber se cobrou. Repetir é a única saída, e sem a chave a repetição cria uma segunda cobrança. Com ela, repetir devolve a primeira.

Os três desfechos

Mesma chave, mesmo corpo → a resposta gravada, com o header Idempotent-Replayed: true. A cobrança não é recriada. Trate como sucesso: o recurso no corpo é o mesmo de antes. Mesma chave, corpo diferente409 idempotency_key_reused. Devolver a cobrança antiga faria você acreditar que cobrou o valor novo. Use uma chave nova. Mesma chave, primeira ainda em voo409 idempotency_key_in_progress. Repita em instantes.
A ordem dos campos no JSON não invalida o retry. Comparamos o conteúdo, não o texto — reserializar o mesmo objeto em outra ordem continua sendo o mesmo corpo.

O que serve de chave

A chave identifica a sua tentativa, não a nossa cobrança. Ela vale por 24 horas e é sua: dois clientes diferentes podem usar pedido-1 sem colidir. Limite de 255 caracteres, ou você recebe 400 idempotency_key_too_long. Uma boa chave é estável e derivada do que você está tentando fazer — o número do pedido, ou um UUID gerado uma vez e gravado junto do pedido.
Gere a chave antes da primeira tentativa e reutilize a mesma em todas as repetições. É esse detalhe que faz a idempotência funcionar — uma chave nova a cada volta do laço tem o mesmo efeito de não enviar chave nenhuma.

Onde ela salva o dia

502 provider_unavailable é o caso clássico. O provedor não respondeu, e pode ser que a cobrança tenha sido criada lá e a resposta se perdido no caminho. Repetir sem chave criaria a segunda; com a mesma chave, você recebe a primeira. O mesmo vale para 500 internal_error e 503 platform_unavailable. É a Idempotency-Key que torna repetir seguro.

Veja também

Repetir com segurança

Quais códigos merecem retry, e com que espera.

Erros

O catálogo completo de códigos.

Ficou algo de fora? Escreva para suporte@usevext.com. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.