Skip to main content

Por que usar

Redes falham. Se sua requisição de POST /runs falhar antes de você receber a resposta, você não sabe se o run foi criado ou não. Sem idempotência, um retry criaria um segundo run — duplicando a consulta. Com Idempotency-Key, você pode fazer retry com segurança: se o run já foi criado com aquela chave, o kycert retorna o resultado original sem executar novamente.

Como usar

Inclua o header Idempotency-Key com um UUID v4 gerado por você:

Comportamento

  • Mesma chave nas próximas 24h: retorna o run original (mesma resposta, mesmo run_id)
  • Chave diferente: cria um novo run
  • Chave expirada (>24h): cria um novo run como se fosse a primeira vez

Regras

  • Use UUID v4 como formato da chave
  • Gere uma chave por tentativa lógica — não por chamada HTTP individual
  • Use a mesma chave em todos os retries da mesma tentativa
  • Não reutilize chaves entre operações diferentes
Se você variar a Idempotency-Key a cada retry, não terá proteção contra duplicação. Se você reutilizar a mesma chave para runs diferentes, poderá receber um resultado incorreto.