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.
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
408or a429 - a
500,502,503or504 - a
409with the codeidempotency_in_progress
It tries each call up to 3 times in all, waiting as long as
Retry-Aftersays when the API sends one. IfRetry-Afteris 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
idempotencyKeyargument.
- TypeScript:
-
Turn the retries off with
maxRetries: 0in TypeScript ormax_retries=0in Python.
- One call starts one run.
reminix.run(...)andreminix runsend a key, so a retried request never starts a second run. - Pass your own key to call again safely. Use
{ idempotencyKey }in TypeScript oridempotency_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 returns400, and every retry gets the same400.
The rules
Section titled “The rules”- Writes only. The header applies to
POST,PUT,PATCHandDELETE. 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_progresswith aRetry-Afterheader. 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
400or a404. 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
- 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.