Skip to main content

Idempotency

The gateway accepts an Idempotency-Key header on all mutating routes (POST/PUT/PATCH/DELETE). Identical key + identical operation within 24 hours returns the cached response from the first call instead of running the operation twice.

When it kicks in automatically​

The SDK auto-generates an idempotency key for every method call:

result, err := client.OCR.Scan(ctx, req)
// SDK sent: Idempotency-Key: client_<uuidv4>

The same key is reused if the SDK retries internally (e.g. transient 5xx). A retry returns whatever the cached first attempt returned, not a fresh OCR run.

When you should pin a key yourself​

For app-level retries (the user taps "Submit" twice; a cron job re-runs), pin a key tied to your domain entity:

client.Liveness.Check(ctx, req,
    ekyc.WithIdempotencyKey("verification-"+verificationID),
)
await sdk.liveness.check(
  mode: LivenessMode.passive,
  frames: [/* ... */],
  idempotencyKey: 'verification-$verificationID',
);

Format and limits​

  • Format: any UTF-8 string, 1-255 characters. Use UUIDs or domain ids — anything stable.
  • Cache TTL: 24 hours. After that, the same key replays the underlying operation.
  • Cache scope: per tenant. Two tenants using the same key don't collide.

Routes that ignore it​

GET requests don't take an idempotency key — they're already idempotent by HTTP semantics. Sending one returns 400 invalid_request to keep the contract clean.