***

title: Idempotency
subtitle: Safely retry requests without duplicating operations
slug: api-guides/idempotency
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/api-guides/llms.txt. For full documentation content, see https://docs.prolifi.io/api-guides/llms-full.txt.

## Overview

The Prolifi API supports idempotency for all mutating requests (`POST`, `PATCH`, `PUT`, `DELETE`). By including an `Idempotency-Key` header, you ensure that the same operation is not executed more than once, even if you retry the request due to a network failure or timeout.

## How it works

1. Include an `Idempotency-Key` header with a unique value (up to 255 characters).
2. Prolifi processes the request normally and caches the response.
3. If you send the same `Idempotency-Key` again, Prolifi returns the cached response instead of re-executing the operation.
4. Cached responses include an `Idempotent-Replayed: true` header so you know the response is a replay.

## Request example

```bash
curl -X POST "https://api.prolifi.co/api/v1/public/customers" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: create-customer-user123-attempt1" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "name": "John Doe"}'
```

If the request times out and you retry with the same `Idempotency-Key`, you will either receive the original response (if it was processed) or the request will be executed for the first time.

## Key guidelines

| Rule           | Detail                                           |
| -------------- | ------------------------------------------------ |
| Maximum length | 255 characters                                   |
| Scope          | Per merchant and API key                         |
| TTL            | Idempotency keys expire after 24 hours           |
| Applies to     | `POST`, `PATCH`, `PUT`, `DELETE` only            |
| Ignored for    | `GET` requests (which are inherently idempotent) |

<Warning>
  If the `Idempotency-Key` header exceeds 255 characters, the request is rejected with a `400` error before any processing occurs.
</Warning>

## Generating idempotency keys

Use a deterministic key derived from the operation being performed. Good strategies:

* **UUID v4** for one-off operations: `Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000`
* **Action-based** for business operations: `Idempotency-Key: create-sub-cust123-plan456`
* **Hash-based** for event reporting: `Idempotency-Key: sha256(customer_id + event_name + timestamp)`

Avoid reusing idempotency keys across different operations, as this will return the cached response from the first operation.

## Replayed responses

When Prolifi returns a cached response, the `Idempotent-Replayed` header is set:

```
HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json

{"data": {"id": "...", ...}}
```

Your application can check for this header to distinguish between first-time and replayed responses, though in most cases the distinction is not important.