Idempotency

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 -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"
  }'

const program = await client.programs.create({
  name: 'Acme Referrals',
  commissionType: 'recurring',
  commissionPercent: 25,
  currency: 'USD',
}, {
  idempotencyKey: 'create-acme-referrals-v1',
})

program = client.programs.create(
    name="Acme Referrals",
    commission_type="recurring",
    commission_percent=25,
    currency="USD",
    idempotency_key="create-acme-referrals-v1",
)

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:

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}`

import uuid

# Option 1: Random UUID
key = str(uuid.uuid4())

# Option 2: Business-meaningful
key = f"payout_{affiliate_id}_{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

Overview

Programs

Affiliates

Applications

Affiliate Self-Serve

Conversions

Payouts

Fraud Flags

Coupons

Invites

Webhooks API

Billing

Merchant

Marketplace

Marketing Resources

How It Works

Behavior

Generating Keys

Best Practices

​How It Works

​Behavior

​Generating Keys

​Best Practices

How It Works

Behavior

Generating Keys

Best Practices