Idempotency
Retry Public API V1 writes without duplicating supported creator, content, deck, or campaign operations.
The following endpoints require an Idempotency-Key header:
POST /creatorsPOST /creator-importsPOST /media-kitsPOST /link-in-bioPATCH /link-in-bioPOST /decksPATCH /decks/{deck_id}POST /campaignsPATCH /campaigns/{campaign_id}
Create a key
Use a unique, non-empty string of at most 128 characters. UUIDs work well.
Idempotency-Key: 6bf0ef96-a2fd-4bdb-86e8-6c62ad62d6e8The 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:
Idempotent-Replayed: trueThe 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
- Create the idempotency key before sending the request.
- Store it with the local operation until the request is resolved.
- Reuse it only for retries of that exact operation and payload.
- If the payload changes intentionally, create a new key.
- Do not generate a new key automatically after a network timeout; doing so can create a second operation.