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.