Skip to content

Idempotency

A request can time out after the API has already acted on it. To retry a write safely, without doing it twice, send an Idempotency-Key header. Any unique string of up to 255 printable ASCII characters works, and a UUID for each operation is a good choice.

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. If you retry the same request with the same key, you get the first response back, with the same status and body, and the operation doesn’t run again. A replayed response carries the header Idempotency-Replayed: true.

What the SDKs, the CLI and the MCP server do

Section titled “What the SDKs, the CLI and the MCP server do”
  • Every write sends a key. If you don’t pass one, the client makes one for that call.

  • The client retries a failed attempt with the same key. It retries after:

    • a network error, or a timeout in Python
    • a 408 or a 429
    • a 500, 502, 503 or 504
    • a 409 with the code idempotency_in_progress

    It tries each call up to 3 times in all, waiting as long as Retry-After says when the API sends one. If Retry-After is longer than 20 seconds, it returns the error to you instead.

  • Pass your own key when you might run the whole call again yourself, for example when a job reruns or you receive a webhook twice. Send the same key both times:

    • TypeScript: { idempotencyKey: id } as the last argument.
    • Python: request_options={"idempotency_key": id}.
    • CLI: --idempotency-key <key>. When a command makes several writes, it derives a key for each one from yours, so running it again with the same key repeats none of them.
    • MCP: every tool that changes something takes an optional idempotencyKey argument.
  • Turn the retries off with maxRetries: 0 in TypeScript or max_retries=0 in Python.

  • One call starts one run. reminix.run(...) and reminix run send a key, so a retried request never starts a second run.
  • Pass your own key to call again safely. Use { idempotencyKey } in TypeScript or idempotency_key= in Python. The run and each file it uploads get keys derived from yours. A second call with the same key and inputs returns the first run.
  • Long runs work the same way. A retry with the same key gets the first response, with the same run id. Follow that run as you would the first time.
  • You can retry a failed upload. If installing a version’s dependencies fails on our side, the upload returns a 5xx. A retry with the same key builds the version again. If the install fails because of something in the folder, the upload returns 400, and every retry gets the same 400.
  • Writes only. The header applies to POST, PUT, PATCH and DELETE. Reads ignore it, since they’re already safe to repeat.
  • One key per request. A key belongs to one request: the same endpoint with the same body. Sending it with a different request fails with 409 idempotency_key_reused. Generate a new key for each operation, and reuse one only to retry that operation.
  • A retry during the first request waits. If the first request is still running, a retry gets 409 idempotency_in_progress with a Retry-After header. Wait that many seconds, then retry.
  • We store only final responses. A final response is a success, or an error a retry would get again, such as a 400 or a 404. Every retry gets that same response back. We don’t store errors a retry might get past. For these, a retry with the same key runs the request again:
    • a 5xx
    • a 402, once you’ve upgraded your plan
    • a 409
    • a 429, once there’s room again
  • A key lasts 24 hours. Each key belongs to the API key or token that sent it, so two integrations never collide. A personal access token’s keys are also separate in each workspace and each environment.
  • We protect stored responses. We keep a hash of your key, never the key itself, and encrypt the stored response with a key derived from yours. Only a retry that sends your key can read it back.

Sending a key yourself is optional. The SDKs, the CLI and the MCP server send one on every write.