Idempotency & Retries

Set an idempotency key

Pass Idempotency-Key when creating an OTP call. Use a unique application verification ID for each new logical request, such as verification-9f10a2.

Idempotency-Key: verification-9f10a2

The server namespaces keys by customer. Replaying an existing key for the same normalized phone number and call mode returns the existing call request rather than creating a new one.

Keep the payload unchanged

Always resend the exact same payload when retrying. The implementation compares normalized destination and call mode when matching an existing request; an idempotency key is not a way to update an existing OTP, recording, or sender. A replay can return the original request even when other body values differ.

A key reused for a different destination or mode returns 409 Conflict. Do not reuse an old key for a new OTP: create a new key for every deliberate resend or new verification.

The API does not advertise an expiry period for idempotency keys. Treat them as unique identifiers and do not recycle them.

Handling network failures

If a connection times out before you receive a response, the call may already have been accepted. Retry the same body with the same key. Avoid an immediate retry with a new key, which can create another call.

Use increasing delays and a retry budget for temporary connection or server failures. Fix validation, account, or balance errors before retrying. Account and balance checks still run when submitting a repeated request.

No idempotency key

Without a key, each successful POST can create a new call. Idempotency is optional in the protocol but recommended for production integrations.