Every POST accepts an Idempotency-Key header: any unique string of 1 to 255 printable characters, such as a UUID. If a request times out or the connection drops, send it again with the same key. You get the original response back, with the header Idempotent-Replayed: true, instead of creating a second payment link or emailing an invoice twice.
curl -X POST https://anytime-capital.com/api/v1/payment-links \
-H "Authorization: Bearer $ANYTIME_API_KEY" \
-H "Idempotency-Key: 5f1c3e0a-7b2d-4c8e-9a61-2d4b8f0e7c13" \
-H "Content-Type: application/json" \
-d '{"title": "Consulting — October", "amountCents": 12500}'How keys behave
| Situation | What you get |
|---|---|
| First request with a key | The request runs and, if it succeeds, its response is remembered with the key. |
| Same key, same request, within the window | The remembered response, with Idempotent-Replayed: true. Nothing runs again. |
| Same key, different body or endpoint | 422 IDEMPOTENCY_KEY_REUSED. Use a new key for a new request. |
| Same key while the first request is still running | The second request waits for the first, then gets its result. |
| The first request failed | Errors are not remembered, so you can fix the problem and retry with the same key. |
| More than 24 hours later | The key is forgotten and the request runs as new. |
| Empty, too long or unprintable key | 400 INVALID_IDEMPOTENCY_KEY. |
| No header | The request simply runs. It is still recorded in your activity log. |
Choosing keys
- Generate one key per operation you mean to happen once, such as “create the payment link for order 1042”, and store it with that order before you call the API.
- Reuse the stored key on every retry of that operation, including after your own process restarts.
- Never reuse a key for a different operation, even for the same customer.
- Keys are scoped to your business: another business using the same string doesn't collide with you.