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

# Idempotency

> Prevent duplicate operations

Idempotency ensures that retrying the same request multiple times has the same effect as making it once. This is crucial for preventing duplicate payments, refunds, and other operations in unreliable network conditions.

## Idempotency-Key Header

ToffeePay supports idempotency for mutation operations (POST requests) using the `Idempotency-Key` header:

```http theme={null}
POST /v1/sessions
Authorization: Bearer <your_access_token>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

...

```

## How It Works

1. **First Request**: ToffeePay processes the request and stores the result with the idempotency key
2. **Duplicate Requests**: If the same idempotency key is used again within 24 hours, ToffeePay returns the cached result instead of processing again
3. **Different Parameters**: If the same key is used with different request parameters, ToffeePay returns an error

## Supported Operations

Idempotency is supported for these operations:

* [Create Session](/api-reference/sessions/create) - Prevents duplicate payment sessions
* [Create Refund](/api-reference/refunds/create) - Prevents duplicate refunds

## Best Practices

### Generate Unique Keys

Use UUIDs or other collision-resistant identifiers:

```typescript theme={null}
import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4(); // e.g., "550e8400-e29b-41d4-a716-446655440000"
```

### Key Per Operation

Use a different idempotency key for each distinct operation:

```typescript theme={null}
// Good: Different keys for different operations
const sessionKey = `session-${userId}-${itemId}-${Date.now()}`;
const refundKey = `refund-${paymentId}-${Date.now()}`;

// Bad: Reusing the same key across different operations
const key = "my-operation-key"; // Don't do this
```

## Error Handling

### Idempotency Conflicts

If you use the same idempotency key with different parameters:

```http theme={null}
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key already used with different parameters"
  }
}
```

### Key Expiration

Idempotency keys expire after 24 hours. After expiration, the same key can be reused.

## Webhook Idempotency

For webhook processing, use the `webhook-id` header to deduplicate events. See the [Webhooks](/webhooks#idempotency) page for details.