> ## Documentation Index
> Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry requests without creating duplicate operations using idempotency keys.

The `X-Idempotency-Key` header allows you to safely retry requests without risk of duplicate operations. When you include an idempotency key, we guarantee that multiple requests with the same key will execute the operation only once.

## How It Works

**First Request**: We process the operation and cache the complete response (including status code, headers, and body) associated with your idempotency key.

**Subsequent Requests**: If we receive another request with the same key, we return the cached response immediately without re-executing the operation.

## Key Requirements

**Generate unique keys per operation**: Generate a unique identifier for each distinct operation. Never reuse keys across different operations.

**Immutable request fingerprint**: For a request to be considered a valid retry, the following must be identical:

* Request method (POST, PUT, etc.)
* Request URL (including path and query parameters)
* Request body (exact byte-for-byte match)
* Request headers that affect processing (e.g., `Content-Type`, `Authorization`)

**Modified requests are rejected**: If you send the same idempotency key with different request data, we'll reject it with `409 Conflict`. This prevents accidental misuse where the same key is reused for a different operation.

## Response Behavior

| Scenario | Response |
| - | - |
| First request with key | Normal processing, response cached |
| Retry with identical request | Cached response returned (same status, headers, body) |
| **Concurrent identical requests** | `409 Conflict` with `idempotency_key_locked` (retry after brief delay) |
| Retry with **modified** request | `409 Conflict` with `idempotency_key_mismatch` (do not retry) |

### Error handling guidance

**Concurrent collision** (`idempotency_key_locked`): A temporary condition when another request with the same key is currently processing. Retry the identical request after a brief delay (100-500ms).

**Request mismatch** (`idempotency_key_mismatch`): The key was previously used with different request parameters. This indicates a programming error—generate a new idempotency key for the new operation.

## Expiration

Idempotency keys expire after 24 hours. After expiration, the same key will be treated as a new operation.

## Best Practices

* Generate keys client-side before making the request
* Store the key with your request context so you can retry with the same key
* Use idempotency keys for all non-idempotent operations (POST, PATCH)
* Don't use predictable patterns (timestamps, sequential IDs)—use cryptographically random values

## Example

```javascript theme={null}
const idempotencyKey = '550e8400-e29b-41d4-a716-446655440000';
const orderData = {
  customerId: 'cust_123',
  items: [...]
};

// First request
const response = await fetch('https://connect.telnesstech.com/api/v2/orders', {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': idempotencyKey,
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(orderData)
});

const result = await response.json();
// Response: 201 Created
// {"orderId": "1b11f175-f0e6-4b6c-8c4b-4eee806123a3", "status": "CONFIRMED", ...}

// Retry (network timeout, uncertain state)
// Use the same idempotency key and request data
const retryResponse = await fetch('https://connect.telnesstech.com/api/v2/orders', {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': idempotencyKey, // Same key
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(orderData) // Same data
});

const retryResult = await retryResponse.json();
// Response: 201 Created (identical to first request)
// {"orderId": "1b11f175-f0e6-4b6c-8c4b-4eee806123a3", "status": "CONFIRMED", ...}
// No duplicate order created
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.