Idempotency in KYC APIs: Why Your Retry Logic Might Be Creating Duplicate Verification Cases
Picture this: your KYC provider's API times out mid-request. Your client retries automatically, because that's what retries are for. Except now you've got two verification cases open for the same user, two review-queue entries for your compliance team, and possibly two charges on your invoice.
This isn't a hypothetical edge case. It's one of the more common ways KYC integrations quietly break in production, and it rarely shows up in testing because local networks don't time out the way real ones do.
Why this bites KYC specifically harder than most APIs
Retrying a failed request is normal engineering practice. The problem is that a KYC verification isn't a simple resource create, it's the start of a workflow: document upload, liveness check, sanctions screening, a human review queue on the other end. If your retry creates a second case instead of resuming the first, you've now got:
- Two entries in a compliance review queue for one person
- Possible double-charging if your provider bills per case
- An audit trail that looks like the same user tried to verify twice, which is exactly the kind of anomaly a reviewer has to stop and investigate
That last one matters more than it sounds. In a regulated flow, "why does this applicant have two verification attempts three seconds apart" is a question someone now has to answer manually.
The fix: idempotency keys, not just retry logic
A basic retry wrapper just resends the request. An idempotent retry sends the request with a client-generated key attached, so the server can recognize "I've already processed this" and return the original result instead of starting a new case.
The key has to be generated once per verification attempt and reused across every retry of that specific attempt, not regenerated on each individual try. Generate it fresh per retry, and every attempt looks like a brand-new request to the server, which defeats the whole mechanism and puts you right back to duplicating cases.
Three things worth checking before you ship this
- Confirm the provider actually honors the key — not every API treats it as authoritative for the full lifetime of a case, only for a short window.
- Persist the key on your side too — if your process restarts mid-retry, an in-memory key is gone and you'll generate a new one on the next attempt.
- Log the key with the case ID — this is what lets you later prove a duplicate-looking entry was a network retry, not the applicant trying to game the system.
Idempotency keys don't remove the need for good case-management design, but they stop your retry logic from actively working against it.
Full breakdown of the design patterns for safe KYC retry recovery: Idempotency in KYC APIs: Why Retry Logic Can Silently Duplicate Cases
