> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry the same logical request with an Idempotency-Key header.

## 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

| Request using the same key and scope | Behavior |
| - | - |
| Matching query and body, with a stored successful response | Returns the original HTTP status and body with `Idempotent-Replayed: true`, without executing the operation again. |
| Matching query and body, while the original request is still processing | Returns `409` with error code `10036`. Retry later with the same key and unchanged request. |
| Different query or body, while the original request is processing or its response is stored | Returns `422` with error code `10027`. Use a new key for an intentionally different operation. |

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.