Idempotency

Network failures, timeouts, and retries can cause your code to issue the same write twice. Idempotency keys let you safely retry mutations without creating duplicates.

How to use it

Pass a unique Idempotency-Key header on any POST, PATCH, or DELETE. We'll cache the response for 24 hours; identical retries with the same key return the cached response instead of running the mutation again.

curl -X POST https://api.tattoobooking.com/v1/clients \
  -H "Authorization: Bearer $TB_API_KEY" \
  -H "Idempotency-Key: client-create-2026-05-27-abc123" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@client.com","first_name":"Jane"}'

Use any unique string up to 255 chars. UUIDs work well. Reuse the same key only when intentionally retrying the same request.

What happens on retry

• Same key + same body. We return the cached response (same status, same body) without running anything. Safe to retry as many times as you like within 24h.
• Same key + different body. We return 422 withcode: idempotency_key_conflict. This protects you from accidentally reusing a key across distinct operations.
• New key. Treated as a fresh request — runs the mutation.

When to use it

Always, on writes. Especially on flows where the cost of a duplicate is high — creating clients, booking appointments, charging payments. Reads (GET) don't need an idempotency key; they're idempotent by definition.

What it doesn't do

It only caches inside our system — once your code calls our API and we respond, the key's job is done. It doesn't protect you against duplicate downstream side effects in YOUR system (e.g., your accounting tool getting the same webhook twice). For that, dedupe by event ID on your side. See the Webhooks doc.