Overview

Network issues happen. When you create a payout and the connection drops before you receive the response, you do not know if the payout was created or not. Retrying could create a duplicate payout -- sending money twice to the same recipient.

Idempotency keys solve this. Include a unique key with your request, and Anton guarantees the operation only happens once, even if you send the same request multiple times.

How to Use

Add the Idempotency-Key header to any POST request:

curl https://api.antonpayments.dev/v1/payouts \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-inv-1042-2026-02-14" \
  -d '{
    "payee_id": "pye_abc123",
    "amount": "500.00",
    "currency": "USD",
    "description": "Invoice #1042"
  }'

If you send the same request with the same idempotency key again, Anton returns the original response instead of creating a duplicate. The response includes an X-Idempotent-Replayed: true header so you know it is a replay.

Key Requirements

Rule	Detail
Unique per operation	Use a different key for each distinct operation
Deterministic	Use the same key when retrying the same operation
Max length	255 characters
Expiry	Keys are remembered for 24 hours, then discarded

Generating Good Keys

Good idempotency keys are unique to the operation and deterministic. Here are three approaches:

UUID (simplest) -- Generate a random UUID for each operation. Simple but requires you to store the UUID for retries.
Deterministic from your data (recommended) -- Derive the key from your business data, such as payout-{invoice_id}-{payee_id}. If your system crashes after sending a request but before processing the response, you can safely retry because the key is deterministic.
Hash of the request body -- SHA-256 hash the request payload. Ensures uniqueness based on the exact request content.

Behavior Details

Same key + same body -- Returns the original response with X-Idempotent-Replayed: true
Same key + different body -- Returns a 409 Conflict error. You cannot reuse a key with a different payload.
Different key + same body -- Creates a new resource. Keys are unique identifiers, not content-based deduplication.

What Idempotency Covers

Idempotency keys are supported on POST requests (create operations), including:

Payout creation
Payee creation
Webhook subscription creation
Batch upload

GET, PUT, and DELETE requests are already naturally idempotent and do not require an idempotency key.

When to Use Idempotency Keys

You should include an Idempotency-Key on every POST request to the Anton API. This is especially critical for payout creation, where a duplicate request could result in sending money twice. Anton validates idempotency key usage during the certification call before you go live.