Idempotency

How to safely retry API requests without creating duplicate resources.

Idempotency lets you safely retry requests without side effects. If a network error occurs and you’re unsure whether your request succeeded, you can retry with the same idempotency key.

How It Works

Include an Idempotency-Key header with POST requests that create or trigger work. The key lets the server return the original result if your client retries the same request after a timeout or network failure.

cURL

curl -X POST https://www.agentref.co/api/v1/programs \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Idempotency-Key: create-acme-referrals-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Referrals",
    "commissionType": "recurring",
    "commissionPercent": 25,
    "currency": "USD"
  }'

Behavior

Scenario	Result
First request with a key	Processed normally, result cached
Retry with same key + same body	Returns cached result (no duplicate)
Retry with same key + different body	409 IDEMPOTENCY_KEY_REUSED error
Key expires (after 24 hours)	Treated as a new request

Generating Keys

Use a UUID v4 or combine business-meaningful values:

Node.js

import { randomUUID } from 'crypto'

// Option 1: Random UUID
const key = randomUUID()

// Option 2: Business-meaningful (prevents duplicates across retries AND code paths)
const key = `payout_${affiliateId}_${period}`

Best Practices

Idempotency keys are only meaningful for mutation requests that accept them. The Node.js and Python SDKs attach idempotency keys to POST requests when you pass the method-specific idempotency option. GET, PATCH, and DELETE requests are not retried through the idempotency cache.

• Always use idempotency keys for create/action requests such as creating programs, invites, payouts, or marketing resources
• Use business-meaningful keys when possible (e.g., payout_{affiliate_id}_{period}) to prevent duplicates even across separate code paths
• Retry with the same key – don’t generate a new key for retries
• Keys expire after 24 hours – after that, the same key can be reused