Skip to content
Reminix Docs

Idempotency

A request can time out after the API has already acted on it. To retry a write without doing it twice, send an Idempotency-Key header: any unique string of up to 255 printable ASCII characters, such as a UUID you generate for each operation.

Terminal window
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2e9a-8b3d-4c47-9a51-0d2f7e4b8c13" \
  -H "Content-Type: application/json" \
  -d '{ … }' \
  https://api.reminix.com/v1/…

The first request with a key runs normally. A retry with the same key and the same request gets the first response again, with the same status and body, and doesn’t run the operation a second time. A replayed response carries the header Idempotency-Replayed: true.

The rules

Section titled “The rules”
  • Writes only. The header applies to POST, PUT, PATCH and DELETE. Reads are safe to repeat anyway, and ignore it.
  • One key per request. Using a key again for a different request, with a different endpoint or body, fails with a 409 and the code idempotency_key_reused. Generate a new key for each operation, and reuse it only to retry that operation.
  • A retry during the first request waits. If the first request is still running, the retry gets 409 idempotency_in_progress and a Retry-After header. Retry after that many seconds.
  • You can retry server errors. A 5xx response isn’t stored, so a retry with the same key runs the request again. Any other response, a success or a 4xx, is what every retry gets back.
  • Per credential, for 24 hours. A key belongs to the API key or token that sent it, so two integrations never collide, and it’s kept for 24 hours.

Sending a key is optional. We recommend it on every write.