Skip to main content
POST /v1/otp/send, POST /v1/otp/verify, and POST /v1/sms/send accept an Idempotency-Key header (max 255 characters). Replaying the same key within 24 hours returns the cached status and body instead of sending a second message or charging twice. Keys are scoped to the workspace that owns the API key. Two customers can send "1" without seeing each other’s responses. Official SDKs generate a key for every POST automatically.
If the header is omitted, the request is not cached and a network retry can double-charge. Prefer always sending a key (or using an SDK). A replayed response carries Idempotent-Replayed: true. A key belongs to one request:
  • The same key on a different endpoint, or with a different body, returns 422 with error.type: idempotency_key_reused. Use a new key for a new request.
  • A repeat that arrives while the first request is still running returns 409 with error.type: request_in_progress. Retry shortly with the same key.
  • Keys longer than 255 characters return 400 validation_error.
A 500 with error.type: internal_error is safe to retry with the same key. So is a 429: rate-limited responses are not kept, so the retry runs again once Retry-After has passed.