Anton.Docs
Dashboard (opens in a new tab)
How it works

Idempotency

A retried request with the same key returns the first response. Keys are kept for 24 hours.

If the connection drops after you call POST /v1/payouts, you cannot tell whether the payout exists, and a blind retry could create a second one. Send an Idempotency-Key with the request. Sending the same request with the same key again returns the original response instead of repeating the work.

Using a key

Add an Idempotency-Key header:

Shell
curl https://api.antonpayments.dev/v1/payouts \
  -X POST \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-inv-1042" \
  -d '{
    "beneficiary_id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
    "instrument_id": "ins_01HX8Z9K0M2N3P4Q5R6S7T8UA2",
    "source_amount": "500.00",
    "source_currency": "USD",
    "destination_amount": "500.00",
    "destination_currency": "USD",
    "method": "ach",
    "fixed_side": "fixed_destination",
    "purpose": "supplier_payment",
    "reference": "INV-1042"
  }'

A replayed response carries Idempotent-Replayed: true. Its body is the original body, at the API version the original request was served at.

When a key is needed

RequestKey
POST that creates or changes something (payouts, beneficiaries, batches, quotes, exchanges, webhooks, evaluations, and so on)Required. Without one the response is 400 missing_idempotency_key.
PATCH and DELETEAccepted, not required.
POST that only calculates and stores nothing (for example POST /v1/intelligence/evaluations/validate)Not needed.
GETNot applicable. Reads are safe to retry.

Each operation's reference page says whether it requires a key.

Key rules

RuleDetail
Unique per operationUse a different key for each distinct operation.
Same key to retryReuse the key when retrying the same operation.
LengthUp to 255 characters.
RetentionKeys are retained for 24 hours.
What is storedOnly a 2xx response. A 4xx or 5xx is not stored, so a retry with the same key runs the request again.

What happens

SituationResult
Same key, same requestThe original response is replayed, with Idempotent-Replayed: true.
Same key, different request body422 idempotency_key_reused. Send a new key for a new request.
Same key while the first request is still running409 idempotency_in_flight. Wait a moment and send it again to get the settled response.
Different key, same bodyA new request. It creates a second resource.
Missing key where one is required400 missing_idempotency_key.
The idempotency check is temporarily unavailable503 idempotency_unavailable. Retry with the same key.

A 5xx is safe to retry with the same key.

A replay is its own request: its Request-Id header is new, while the body keeps the original request's identifiers, including error.request_id on a replayed error.

Secrets are not replayed

Some responses carry a secret that is shown once: a webhook subscription's signing secret and a verification's hosted_link. A replay returns the same resource with the secret set to null. Save the secret from the first response. If you lost it, rotate the webhook secret or regenerate the verification.

Generating keys

Derive the key from your own data. After a crash the retry produces the same key, so you do not need to remember whether the first request went through.

curl ... -H "Idempotency-Key: payout-${INVOICE_ID}-${BENEFICIARY_ID}"

What idempotency does not do

  • It does not deduplicate on the body. A different key with the same body is a new request.
  • It does not replay a payout's later lifecycle. Outcomes arrive by webhook.

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗