Idempotency
Safely retry mutations with Idempotency-Key headers.
2 min read
Network failures happen. The Idempotency-Key header ensures that retrying a request doesn't create duplicate resources.
How It Works#
- Include an
Idempotency-Keyheader with a unique string on any POST, PATCH, or DELETE request - If the request succeeds, the response is cached for 24 hours keyed by (user, idempotency key)
- If you retry with the same key, the original response is returned immediately without re-executing the operation
- The
Idempotent-Replayed: trueheader indicates a cached response
Usage#
bash
curl -X POST https://api.chamelingo.com/api/v1/decks \
-H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
-H "Idempotency-Key: create-food-deck-2026-03-20" \
-H "Content-Type: application/json" \
-d '{"title": "Food Vocabulary"}'
If this request is sent twice with the same key, the deck is only created once.
Key Format#
- Maximum length: 255 characters
- Any string works — UUIDs, descriptive names, or hashes
- Keys are scoped per user — different users can use the same key without collision
- Keys expire after 24 hours
When to Use#
Use idempotency keys on all mutation requests where duplicate execution would be harmful:
| Endpoint | Recommended |
|---|---|
POST /decks | Yes — prevents duplicate decks |
POST /decks/:id/cards | Yes — prevents duplicate cards |
POST /decks/:id/cards/import | Yes — prevents duplicate imports |
POST /reviews | Optional — duplicate reviews are harmless (same ratings reapplied) |
POST /chat | No — each message is intentionally unique |
GET Requests#
GET requests are naturally idempotent — the Idempotency-Key header is silently ignored on GET requests.
Tip
For import operations, use a hash of the card data as the idempotency key. This way, importing the same card set always returns the cached result.