# Idempotency

> Retry Public API V1 writes without duplicating supported creator, content, deck, or campaign operations.
>
> Canonical URL: https://docs.creatorsjet.com/api/idempotency

The following endpoints require an `Idempotency-Key` header:

* `POST /creators`
* `POST /creator-imports`
* `POST /media-kits`
* `POST /link-in-bio`
* `PATCH /link-in-bio`
* `POST /decks`
* `PATCH /decks/{deck_id}`
* `POST /campaigns`
* `PATCH /campaigns/{campaign_id}`

## Create a key

Use a unique, non-empty string of at most 128 characters. UUIDs work well.

```http
Idempotency-Key: 6bf0ef96-a2fd-4bdb-86e8-6c62ad62d6e8
```

The key is isolated by subject, HTTP method, and route. Records are retained for 24 hours.

## Retry behavior

If the original request completed, an identical retry returns the stored status and response body and includes:

```http
Idempotent-Replayed: true
```

The request fingerprint includes the canonical JSON body and, for imports, the uploaded file bytes.

| Situation                                         | Result                        |
| ------------------------------------------------- | ----------------------------- |
| Same key and same payload after completion        | Original response is replayed |
| Same key with a different payload                 | `409 IDEMPOTENCY_KEY_REUSED`  |
| Same key while the original request is unfinished | `409 IDEMPOTENCY_IN_PROGRESS` |
| Same key after the 24-hour record expires         | Treated as a new request      |

## Recommended pattern

1. Create the idempotency key before sending the request.
2. Store it with the local operation until the request is resolved.
3. Reuse it only for retries of that exact operation and payload.
4. If the payload changes intentionally, create a new key.
5. Do not generate a new key automatically after a network timeout; doing so can create a second operation.