Sign in

Retries and conflicts

Retry without doing things twice; change without overwriting others.

Idempotency-Key: retry without doing it twice#

Send Idempotency-Key (a UUID) with every POST. If the answer gets lost and you retry with the same key within 24 hours, you get the first answer again, marked Idempotent-Replayed: true, and nothing is done twice: no second mail, no duplicate invoice.

SHELL
KEY=$(uuidgen)
curl -X POST https://api.zilomail.in/v1/invoice/receipts -H "Authorization: Bearer $T" \
  -H "Idempotency-Key: $KEY" -H "Content-Type: application/json" -d @receipt.json
# timed out? the same command again, the same KEY: one receipt.
  • The same key with a different body: 422.
  • The first request still running: 409 (wait, retry).
  • Server errors aren't kept: a retry runs again.

If-Match: don't overwrite someone else's change#

Records you can change come with an ETag. Send it back as If-Match when you change the record: if someone changed it since you read it, you get 412 precondition_failed instead of overwriting their work. Read it again, merge, retry.

HTTP
GET /v1/invoice/customers/c7a1…        →  ETag: W/"q1v0G4o0sT1nDkx2V9e4Lg"
PATCH /v1/invoice/customers/c7a1…
If-Match: W/"q1v0G4o0sT1nDkx2V9e4Lg"
{ "creditLimit": 50000 }                →  200, or 412 if it changed meanwhile