Skip to main content

​
Overview

All POST endpoints accept an optional Idempotency-Key header. When provided, the API guarantees that the same operation is performed at most once, regardless of how many times the request is sent. This protects against duplicate payouts and other unintended side effects caused by network retries. GET requests are inherently idempotent. The header is silently ignored if sent on a GET.

​
Usage

Include the Idempotency-Key header on any POST request: 
curl -X POST https://api.augustus.com/v1/payouts \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: 7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.50", "currency": "EUR", ... }'
Keys can be any string up to 255 characters. V4 UUIDs work well, as do business-meaningful identifiers like an internal invoice ID. The SDK auto-generates a fresh idempotency key for every write request if you don’t provide one, so you get safe retries by default.

​
Replay behavior

When a request with a previously used idempotency key and identical parameters is received, the API returns the cached response from the original request. The Idempotent-Replayed: true header distinguishes a replay from a fresh creation: 
HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payout",
  "status": "pending",
  ...
}

​
Mismatch behavior

Reusing an idempotency key with different request parameters returns 409 Conflict: 
{
  "category": "idempotency_error",
  "code": "idempotency_key_already_used",
  "message": "This idempotency key has already been used with different parameters.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

​
Concurrent requests

If a second request with the same key arrives while the first is still processing, the API returns 409 Conflict with code request_in_progress. Retry after a short delay. Once the original completes, retries will return the cached result.

​
Error handling

Only successful responses are cached. If a request fails (e.g. 400 validation error), the key is released and you can retry with the same key after fixing the request.

​
Key retention

Idempotency keys are retained for 30 days. After expiry, a previously used key is treated as new.

​
Key scoping

Keys are scoped globally across all endpoints per merchant account. Reusing the same key on a different endpoint returns the cached result from the first request or triggers a mismatch error. Different merchant accounts can use the same key independently.