Skip to main content
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 any POST request: 
curl -X POST https://www.agentref.co/api/v1/conversions \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Idempotency-Key: unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{"programId": "prg_abc", "affiliateId": "aff_xyz", "amount": 9900}'

​
Behavior

ScenarioResult
First request with a keyProcessed normally, result cached
Retry with same key + same bodyReturns cached result (no duplicate)
Retry with same key + different body409 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: 
import { randomUUID } from 'crypto'

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

// Option 2: Business-meaningful (prevents duplicates across retries AND code paths)
const key = `order_${orderId}_conversion`

​
Best Practices

Idempotency keys are only meaningful for POST requests. GET, PATCH, and DELETE requests are naturally idempotent.
  • Always use idempotency keys for conversion creation and payout requests
  • Use business-meaningful keys when possible (e.g., order_{id}_conversion) 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