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 headerIdempotent-Replayed: true. A
cobrança não é recriada. Trate como sucesso: o recurso no corpo é o mesmo de antes.
Mesma chave, corpo diferente → 409 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 voo → 409 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 usarpedido-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.
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.