Idempotency

How it works

When you send a POST request with an X-Idempotency-Key header, Dark Obsidian:

1. Computes a SHA-256 hash of the key + request body
2. Checks if this hash exists in the deduplication store
3. If found: returns the cached response (no side effects)
4. If not found: processes the request and caches the response for 7 days

Headers

Example

curl -X POST \
  https://qatxonlxvtgxvqjgfxpl.supabase.co/functions/v1/api/orders \
  -H "Authorization: Bearer do_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"items": [{"product_id": "uuid", "quantity": 1}]}'

const order = await client.orders.create(
  { items: [{ product_id: 'uuid', quantity: 1 }] },
  {
    idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
    correlationId: 'req-abc-123',
  }
)

order = client.orders.create(
    items=[{'product_id': 'uuid', 'quantity': 1}],
    idempotency_key='550e8400-e29b-41d4-a716-446655440000',
    correlation_id='req-abc-123',
)

Conflict response

When the same key is used with a different request body:

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency key already used with different parameters",
    "docs": "https://darkobsedian.sameergul.com/docs/errors#IDEMPOTENCY_CONFLICT"
  }
}

Best practices

• Use UUIDs (v4) for idempotency keys
• Include the same key when retrying a failed request
• Never reuse a key for a different operation
• Keys expire after 7 days - after that, a new request with the same key will be processed normally