Idempotency

Overview

Idempotent requests allow you to safely retry API calls without the risk of performing the same operation twice. This is essential for building reliable integrations, especially when dealing with network failures or timeouts.

How It Works

To make an idempotent request, include an Idempotency-Key header with a unique value. If the same key is used within 24 hours, the API returns the cached response from the first request instead of creating a new resource.

import requests

response = requests.post(
    'https://api.infinite.dev/v1/customers/individuals',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Idempotency-Key': 'unique-key-123',
        'Content-Type': 'application/json',
    },
    json={
        'customerName': 'John Doe',
        'email': 'john@example.com',
        'countryCode': 'US',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/individuals',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Idempotency-Key': 'unique-key-123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerName: 'John Doe',
      email: 'john@example.com',
      countryCode: 'US',
    }),
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api POST /v1/customers/individuals \
  --header 'Idempotency-Key: unique-key-123' \
  --body '{
  "customerName": "John Doe",
  "email": "john@example.com",
  "countryCode": "US"
}'

Create an individual customer John Doe (john@example.com) in the US, using idempotency key unique-key-123.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl https://api.infinite.dev/v1/customers/individuals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "John Doe",
    "email": "john@example.com",
    "countryCode": "US"
  }'

First Request

Processes the request normally
Creates the resource
Stores the request and response for 24 hours
Returns the newly created resource

Subsequent Requests (Same Key)

Detects duplicate key
Returns the cached response immediately
No new resource is created
No side effects occur

Supported Endpoints

Idempotency is supported on the following resource creation endpoints:

Customers: POST /customers/individuals, POST /customers/businesses
Associated Entities: POST /customers/:customerId/associated_individuals, POST /customers/:customerId/associated_businesses
Transfers: POST /transfers
Quotes: POST /quotes
FX Quotes: POST /fx/quotes
Balance Accounts: POST /balance-accounts
Fixed Routes: POST /fixed-routes/virtual-bank-accounts, POST /fixed-routes/virtual-wallets

Endpoints not listed here ignore the Idempotency-Key header — retrying a request against them may create duplicate resources.

Generating Idempotency Keys

Idempotency keys should be:

High-entropy: Use UUIDs — do not derive keys from guessable values like sequential order numbers
Stable across retries: Generate the key once per operation, persist it, and reuse the same value for every retry of that operation
Short-lived: Keys expire after 24 hours

Best Practices

Generate a UUID when the operation is first attempted and store it alongside the operation with an atomic get-or-create, then reuse that stored value for every retry:

// Good: compare-and-set so concurrent first attempts converge on one key
const candidateKey = crypto.randomUUID();
const result = await db.query(
  `UPDATE orders
   SET idempotency_key = COALESCE(idempotency_key, $1)
   WHERE id = $2
   RETURNING idempotency_key AS "idempotencyKey"`,
  [candidateKey, orderId]
);
const idempotencyKey = result.rows[0].idempotencyKey;

A plain read-then-write can lose under concurrency: two workers both see no key, generate different UUIDs, and then retry with different keys. Serialize retries of the same operation: wait for a response or timeout before sending another request with the same key. Do not fire overlapping concurrent requests with one key. Avoid these patterns:

// Bad: including a timestamp makes every retry a new key
const badTimestampKey = `create-customer-${customerId}-${Date.now()}`;

// Bad: guessable, low-entropy keys risk collisions
const badGuessableKey = `create-transfer-${orderNumber}`;

// Bad: reusing the same key for different operations
const badSharedKey = 'my-key';

Error Handling

If the original request failed, subsequent requests with the same key will return the same error. This prevents partial state issues.

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Idempotency-Key': 'retry-key-456',
    'Content-Type': 'application/json',
}

# First request fails (missing required fields)
requests.post(
    'https://api.infinite.dev/v1/customers/individuals',
    headers=headers,
    json={'email': 'invalid'},
)
# Response: 400 Bad Request

# Retry with same key — cached error is returned even if body changed
requests.post(
    'https://api.infinite.dev/v1/customers/individuals',
    headers=headers,
    json={'name': 'Fixed', 'email': 'valid@example.com'},
)
# Response: 400 Bad Request (same error cached)

// First request fails (missing required fields)
await fetch('https://api.infinite.dev/v1/customers/individuals', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Idempotency-Key': 'retry-key-456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'invalid' }),
});
// Response: 400 Bad Request

// Retry with same key — cached error is returned even if body changed
await fetch('https://api.infinite.dev/v1/customers/individuals', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Idempotency-Key': 'retry-key-456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Fixed', email: 'valid@example.com' }),
});
// Response: 400 Bad Request (same error cached)

export INFINITE_API_KEY=YOUR_API_KEY

# First request fails
infinite api POST /v1/customers/individuals \
  --header 'Idempotency-Key: retry-key-456' \
  --body '{"email": "invalid"}'
# Response: 400 Bad Request

# Retry with same key — cached error is returned
infinite api POST /v1/customers/individuals \
  --header 'Idempotency-Key: retry-key-456' \
  --body '{"name": "Fixed", "email": "valid@example.com"}'
# Response: 400 Bad Request (same error cached)

Create an individual customer with idempotency key retry-key-456 and an invalid body, then retry with the same key — the cached 400 comes back.

# Infinite MCP is read-only today — run the CLI tab to execute.

# First request fails
curl -X POST https://api.infinite.dev/v1/customers/individuals \
  -H "Idempotency-Key: retry-key-456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "invalid"}'

# Response: 400 Bad Request

# Retry with same key (body may differ — cached error is returned)
curl -X POST https://api.infinite.dev/v1/customers/individuals \
  -H "Idempotency-Key: retry-key-456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fixed", "email": "valid@example.com"}'

# Response: 400 Bad Request (same error cached)

To fix the request, use a new idempotency key.

Key Expiration

Idempotency keys expire after 24 hours. After expiration:

The key can be reused for a new operation
Previous responses are no longer cached

When to Use

✅ Use Idempotency For:

Network retry logic
Webhook handlers (use webhook event ID as key)
User-triggered actions that could be double-clicked
Automated scheduled jobs
Any situation where duplicate requests are possible

❌ Don’t Use For:

Read operations (GET requests) - they’re naturally idempotent
Update operations (PATCH/PUT) - these are typically idempotent by design
Operations you want to repeat intentionally

Implementation Examples

JavaScript/TypeScript

import { v4 as uuidv4 } from 'uuid';

async function createCustomer(data: CustomerData) {
  const idempotencyKey = uuidv4();

  try {
    const response = await fetch(
      'https://api.infinite.dev/v1/customers/individuals',
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
      },
    );

    return await response.json();
  } catch (error) {
    // Safe to retry with same key
    return await retryWithSameKey(idempotencyKey, data);
  }
}

Python

import uuid
import requests

def create_customer(data):
    idempotency_key = str(uuid.uuid4())

    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Idempotency-Key': idempotency_key,
        'Content-Type': 'application/json',
    }

    try:
        response = requests.post(
            'https://api.infinite.dev/v1/customers/individuals',
            headers=headers,
            json=data
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        # Safe to retry with same key
        return retry_with_same_key(idempotency_key, data)

Webhook Handler Example

// Use webhook event ID as idempotency key
async function handleWebhook(event: WebhookEvent) {
  const idempotencyKey = event.id; // Webhook event ID

  await createTransfer(
    {
      // ... transfer data
    },
    idempotencyKey
  );
}

Technical Details

Storage: Idempotency keys are stored in the database
TTL: 24 hours from first request
Scope: Keys are scoped by operation type. Related routes that create the same resource type share one cache (for example POST /customers/individuals and POST /customers/businesses; similarly the two associated-entity create routes). Always use a unique high-entropy UUID per distinct operation — never guessable or shared values.
Cleanup: Expired keys are automatically cleaned up

Limitations

Do not reuse a key across different operations — reusing one can return the first cached response
Related creation routes that create the same resource type share one cache; reuse a key only when retrying that same operation
Do not send overlapping concurrent requests with the same key — wait for a response or timeout, then retry
Maximum key length: 255 characters
Only POST operations support idempotency (creation endpoints)

Get started

Core Concepts

Guides

Overview

How It Works

First Request

Subsequent Requests (Same Key)

Supported Endpoints

Generating Idempotency Keys

Best Practices

Error Handling

Key Expiration

When to Use

✅ Use Idempotency For:

❌ Don’t Use For:

Implementation Examples

JavaScript/TypeScript

Python

Webhook Handler Example

Technical Details

Limitations

​Overview

​How It Works

​First Request

​Subsequent Requests (Same Key)

​Supported Endpoints

​Generating Idempotency Keys

​Best Practices

​Error Handling

​Key Expiration

​When to Use

​✅ Use Idempotency For:

​❌ Don’t Use For:

​Implementation Examples

​JavaScript/TypeScript

​Python

​Webhook Handler Example

​Technical Details

​Limitations

Overview

How It Works

First Request

Subsequent Requests (Same Key)

Supported Endpoints

Generating Idempotency Keys

Best Practices

Error Handling

Key Expiration

When to Use

✅ Use Idempotency For:

❌ Don’t Use For:

Implementation Examples

JavaScript/TypeScript

Python

Webhook Handler Example

Technical Details

Limitations