Developer Guide

Idempotency & Retry Safety Blueprint

Design safe integration pipelines that handle network timeouts and retries without duplicate data mutations or double billing.

← Developer Hub Overview Webhooks Guide →

Idempotency state machine comparing first write execution with second cached retry response

Retry Governance

Idempotency Execution Rules

Principle 01

Pass Idempotency-Key Header: Provide a unique V4 UUID for POST/PATCH state mutations.

Principle 02

24-Hour Cache Window: Idempotency keys are cached for 24 hours. Repeating the key returns the cached response.

Principle 03

Safe Concurrent Lock: Simultaneous requests with the same key receive HTTP 409 Conflict while processing.

Principle 04

Payload Match Check: Retrying a key with a different payload body returns HTTP 422 Unprocessable Entity.

Idempotent Request Header Sample

Include Idempotency-Key in write HTTP requests. Retrying this key within 24 hours returns the cached HTTP response.

curl -X POST https://api.example.invalid/v1/messages \
  -H "Authorization: Bearer indotium_test_token_123" \
  -H "Idempotency-Key: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+15550192834",
    "channel": "sms",
    "body": "Your verification code is 849201"
  }'