API Admin › Guias

Escrita repetível (Idempotency-Key)

A rede cai no meio da chamada: a escrita aconteceu ou não? Com o cabeçalho Idempotency-Key, repetir a mesma escrita é seguro: ela acontece uma vez só.

curl -X POST https://api.denaryx.com/admin/2026-10/... \
  -H "Authorization: Bearer dnxa_..." \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Vale em POST, PUT, PATCH e DELETE. É opcional, mas recomendado em toda escrita.
A chave é sua: de 1 a 255 caracteres (fora disso, 400 invalid_idempotency_key). Um UUID novo por escrita é o mais simples.
A chave vale 24 horas, por integração (ou por acesso do login do CLI).
Nos envios de arquivo (multipart/form-data), o corpo comparado inclui o conteúdo de cada arquivo: o mesmo envio repetido devolve a resposta guardada, e outro arquivo com a mesma chave é 422.
O segredo de um webhook (secret, na criação e na troca) não fica guardado: a repetição devolve o webhook sem ele. Se perdeu a primeira resposta, troque o segredo (Webhooks).

Situação	Resposta
Chave nova	A escrita acontece, e a resposta fica guardada.
Mesma chave, mesmo método, mesmo caminho e mesmo corpo	A resposta guardada, sem escrever de novo, com o cabeçalho `Idempotent-Replayed: true`.
Mesma chave com outro corpo, método ou caminho	422 `idempotency_key_reused`.
Mesma chave enquanto a primeira chamada ainda roda	409 `idempotency_key_in_use`. Espere a primeira terminar e repita.
A escrita falhou (qualquer erro)	A chave é solta: repetir com ela tenta de novo.

Se a primeira chamada ficar presa por mais de um minuto sem resposta (um reinício do servidor no meio), a chave é liberada para a repetição.