General
Idempotency
Every write takes an idempotency key, so a timeout is something you retry rather than something you investigate.
curl https://api.veruapis.com/v1/messages/send \
-H "Authorization: Bearer vak_live_..." \
-H "Idempotency-Key: 3f8c2e8d-1a4b-4c7e-9f21-0242ac130003" \
-d '{ "to": ["[email protected]"], "subject": "Nightly report", "text": "All green." }'A write without the header is refused with
400 idempotency_key_required. Making it optional would
mean most callers discover they needed it after sending the same email
twice.
What happens on a retry
| Situation | Result |
|---|---|
| Same key, same body, first request finished | The original response, with Idempotency-Replayed: true. Nothing happens twice. |
| Same key, same body, first request still running | 409 idempotency_key_in_flight. Wait and retry. |
| Same key, different body | 409 idempotency_key_reuse. The key is bound to the request it was first used with. |
| A new key | A new operation. |
Choosing a key
A UUID per operation is the simple answer. Better still, derive it from what makes the operation unique in your own system: the invoice id, the row id, the date of the nightly run. Then a retry after a crash reuses the same key without you having had to store it.
Keys are kept for 24 hours. After that the same key starts a new operation, so a retry a day later will genuinely send again.