Skip to main content

Idempotency

A network can fail after the server has acted. To retry a write without doing it twice, send an Idempotency-Key header: any unique string, a UUID is best.

curl -X POST "https://api.zaitrack.app/v1/dispatch/jobs" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: 5b0e3f4c-2d1a-4c7e-9f8b-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d @job.json

What the gateway does​

For each operation that takes a key (each one's page in the API reference says Optional or Required):

  1. First request: the gateway claims the key for your organisation, passes the request on and keeps the response for 24 hours.
  2. Same key, same body: you get the stored response, with Idempotency-Replayed: true. Nothing runs again.
  3. Same key, different body: 409 with code idempotency.body_mismatch.
  4. Same key while the first request is still running: 409 with code idempotency.in_flight. Wait and retry.
  5. The first request failed with a 5xx: the key is released, so a retry with it runs again.

Keys are per organisation: two organisations can use the same string. A response larger than 1 MiB is not stored: the key stays used for its 24 hours and a retry with it gets idempotency.in_flight, so use a new key to run such a request again. A claim whose first response never lands (the gateway lost the request) lapses after 5 minutes.

Where a key is required​

POST /v1/commands (send a command to a device) refuses a request without one: 400 with code idempotency.required. Everywhere else the key is optional, and recommended on every create and action.

If the idempotency store is unreachable the gateway refuses the write (503, idempotency.unavailable) rather than risk running it twice.