Skip to main content

​
Idempotency-Key

An opaque, unquoted key for safely retrying the same logical request. Use this header on endpoints whose API reference declares Idempotency-Key support. The endpoint reference specifies whether the header is optional or required. This page describes the Telnyx general idempotency behaviour, however some endpoints may implement a different contract. Follow its API reference for endpoint-specific requirements

​
Key format

Keys must contain 1 to 255 letters, numbers, hyphens, underscores, or colons. Pattern: ^[A-Za-z0-9_:-]{1,255}$ Example: 8e03978e-40d5-43e8-bc93-6894a57f9326

​
Retries

Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

​
What counts as the same request

Telnyx identifies an idempotency record using the key, your organization, the HTTP method, and the URL path. Requests from different users or API keys belonging to the same organization can therefore match the same record. For the same organization, method, and path, changing the query parameters or body returns 422 while the original record exists. For disambiguation we use:
  • Query parameters: same parameters with the same values will count as the same request
  • Request body: the body must be byte-for-byte identical to count as the same request
  • Request headers: these are not taken into account. The same request body/params with different headers will count as the same request

​
Replay and concurrent requests

For example, if a request with key order-123 succeeds, retrying it with the same query and exact body replays that success. Reusing order-123 with a changed body returns 422. Changing only an ordinary request header still matches the original request and can replay the original response. Only successful 2xx responses are stored. After the stored response expires, the key can be processed as a new request; do not rely on it to prevent duplicates beyond the 24-hour retention window.

​
Error responses

Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A matching request already in progress with the same key returns 409; reusing the key with a different request in the same scope returns 422.