Get started
Idempotency
Send a request again without repeating what it did.
A request can time out after the server has acted on it. If you send it again, you do not want a second call, a second batch run or a second top-up. An Idempotency-Key prevents that.
How to use it
Add the header to a supported POST, with a value that is unique for the action (a UUID, or your own order id):
curl -X POST https://api.sevennadi.si/call \
-H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reminder-INV-2041" \
-d '{"agent_id": "123e4567-e89b-12d3-a456-426655440000", "recipient_phone_number": "+919876500000"}'If you send the same request with the same key again, you get the first response back, with the header Idempotency-Replayed: true. Nothing is done twice.
Rules
| Situation | Result |
|---|---|
| Same key, same request | The stored response, Idempotency-Replayed: true |
| Same key, different request (method, path, query or body) | 409 |
| Same key while the first request is still running | 409. Try again shortly. |
| The first answer was a 5xx | Not stored. Retry with the same key. |
| No header | The request runs normally, every time. |
- A key is 1 to 200 printable ASCII characters, without spaces.
- Keys are kept for 24 hours by default, per workspace.
- A request that never finished (a crash) stops blocking its key after two minutes.
- Bodies over 30 MB are passed through without idempotency.
Where it applies
| Endpoint |
|---|
POST /call |
POST /batches |
POST /batches/{batch_id}/schedule |
POST /workflow-campaigns |
POST /workflow-campaigns/{campaign_id}:start |
POST /workflow-campaigns/{campaign_id}:resume |
POST /workflows/{workflow_id}/run |
POST /billing/topups |
POST /billing/plan |
POST /team/invites |
POST /phone-numbers/buy |
POST /public/leads |
POST /public/callback |
On every other route the header is ignored. For the public website forms the key is scoped to the client address instead of a workspace.
Charges are idempotent on their own
Separately from this header, every wallet movement has a unique reference (for a call, the execution id). A call cannot be charged twice, whatever is retried inside the platform. See Billing.