Idempotency
Send an Idempotency-Key header with every write. If a request is repeated with the same key, Sparro returns the first result and does not create a second record. That makes a retry after a timeout safe.
request
POST /api/v2/shifts
Idempotency-Key: 6d0c2f1e-9b7a-4c55-8f31-0a2e4b9d7c10Rules
| Case | Result |
|---|---|
| Same key, same request | The first response again, with Idempotent-Replayed: true. No second record. |
| Same key, different request | 422 idempotency_key_reuse |
| Same key while the first request is still running | 409 idempotency_request_in_progress with Retry-After. Wait, then repeat it. |
| No key on a write | 400 idempotency_key_required |
| A key that is not 8 to 128 printable ASCII characters | 400 idempotency_key_invalid |
| The first request failed | It is not remembered. Fix the request and send it again, with the same key or a new one. |
| After 24 hours | The key is forgotten and the request is new. |
Same key, same request
The first response again, with
Idempotent-Replayed: true. No second record.Same key, different request
422 idempotency_key_reuseSame key while the first request is still running
409 idempotency_request_in_progress with Retry-After. Wait, then repeat it.No key on a write
400 idempotency_key_requiredA key that is not 8 to 128 printable ASCII characters
400 idempotency_key_invalidThe first request failed
It is not remembered. Fix the request and send it again, with the same key or a new one.
After 24 hours
The key is forgotten and the request is new.
Use a new random UUID for each logical operation, and reuse it only when you retry that operation. A key is matched against your own app's requests for one company, so keys do not collide with other apps. Requests larger than 4,096 bytes are refused.