Idempotency ​

The Developer API supports an Idempotency-Key header on POST/PUT requests so safe retries (after network flakes, automation re-runs, or webhook re-deliveries) never create duplicates.

Using Idempotency-Key ​

POSTs and PUTs accept an Idempotency-Key header (up to 128 characters):

POST /api/v1/leads
Authorization: Bearer kpa_live_…
Content-Type: application/json
Idempotency-Key: 8f2c4e8b-1234-…

{ "student_name": "Anna Smith", ... }

Within 24 hours, replays of the same key (against the same endpoint with the same method) return the original response — no duplicate creation, no double-execution.

How it works:

  1. First call: Idempotency-Key: foo. Request executes normally. Response cached keyed (api_key_id, method, path, "foo") for 24h.
  2. Replay within 24h: cache hit → return original status + body + headers, plus Idempotent-Replayed: true.
  3. Different request body with the same key: returns 409 Conflict.

When to use idempotency ​

Always use it for POSTs and PUTs in production integrations. Why:

  • Network flakes cause retries. Without idempotency, a retried "create lead" makes two leads.
  • Webhook re-deliveries can cause double-writes on the receiving end.
  • Make.com / n8n's automatic retries can fire 3-5 times on transient errors.

The pattern: generate a UUID once per logical operation (in your Make/n8n scenario, on your script's main loop), reuse it for retries.

What idempotency does NOT do ​

  • Doesn't dedupe based on body content. If you POST the same body twice without an idempotency key, you'll create two leads.
  • Doesn't cache 5xx responses. If we return 500, we don't cache that — your retry runs fresh.
  • Doesn't span keys. Two different API keys using the same idempotency key string don't share cache.
  • Doesn't persist beyond 24h. A 25th-hour retry executes again.

Example: idempotent lead creation ​

bash
IDEMP_KEY="$(uuidgen)"

for i in 1 2 3; do
  echo "Attempt $i"
  curl -X POST \
    -H "Authorization: Bearer kpa_live_xxx" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMP_KEY" \
    -d '{"student_name":"Anna","parent_email":"[email protected]"}' \
    https://your-kinderpedia.com/api/v1/leads
done

Attempt 1 creates the lead. Attempts 2 + 3 return the same 201 Created response with the same lead id and Idempotent-Replayed: true.

Replay headers ​

Replayed responses carry an extra header:

Idempotent-Replayed: true

If you don't see this header on a retry, you may have either:

  • Used a different idempotency key (or no key) → fresh execution happened
  • Retried after the 24h window → fresh execution happened
  • Hit an error response that wasn't cached (5xx) → fresh execution happened

Best practices ​

  • Always include Idempotency-Key on POST/PUT. Negligible cost; massive safety.
  • Use UUIDs. uuidgen / crypto.randomUUID() / Make.com's uuid() function — anything random.
  • Don't reuse keys across operations. One UUID per logical write.
  • Treat 409 Conflict seriously. It means you sent the same key with a different body — fix your client.

Kinderpedia Admissions Help Center

Copyright © 2026 Kinderpedia