Idempotency
How idempotency keys make Soljio commands safe to retry, what a replay returns, and which mistakes cause a 409 idempotency_conflict.
A command that times out leaves you unsure whether it ran. An idempotency key resolves that: send the same command with the same key again, and Soljio returns the original result instead of doing the work twice. No second program is created, no second invitation is sent, and no second refund is recorded.
Which requests need a key
Every command, meaning every POST /v0/commands/{operation} request, needs an Idempotency-Key header. That includes dry runs, previews, and commands that queue background work. Queries and resource reads do not use keys.
POST /v0/commands/create_program HTTP/1.1
Host: api.soljio.com
Authorization: Bearer soljio_sk_REPLACE_WITH_YOUR_TOKEN
Content-Type: application/json
Idempotency-Key: create-program-learn-to-swim-2026-01
{"name":"Learn to Swim","status":"draft"}
A key is 1 to 128 visible ASCII characters, with no spaces. A missing or invalid key returns 400 with invalid_request before the command runs.
What a key is scoped to
Soljio remembers a key for the combination of:
- the school,
- the service token that sent it,
- the API version (
v0), and - the command name.
So the same key can be used for two different commands without interference, and two tokens can use the same key without sharing results. It also means that a request sent with a rotated token is a different request for idempotency purposes. Do not rotate a token while a retry sequence is in flight. See Authentication.
What a replay returns
When Soljio sees a key it has already completed, with the same input, it returns the saved result:
- the original
dataand the original status, including201or202and theLocationheader, - the original
request_idin the body, "idempotent_replay": true,- a fresh
X-Request-Idheader that identifies this attempt.
Nothing is written again. Queued jobs are not queued again, and no second success audit entry is recorded.
{
"data": { "ok": true, "program_id": "PROGRAM_ID" },
"idempotent_replay": true,
"request_id": "00000000-0000-4000-8000-000000000002"
}
A replay still has to pass the credential and scope checks. If the token was revoked or lost a required scope since the first attempt, the replay is refused with 401 or 403 and the saved result is not returned. Replays also count toward your rate limit.
Same key, different input
Soljio compares the JSON content of the request, not its formatting or the order of its properties. If you reuse a key with different content for the same command, the request fails with 409 and the error code idempotency_conflict. Nothing runs.
Use a new key for every distinct logical operation. Reuse a key only to retry the exact same one.
What gets recorded
Only successful commands are recorded. These outcomes do not use up a key, so you can send the same key again once you have fixed the cause:
- validation failures (
400), - a missing scope (
403), - a conflict with the current state (
409conflict), - a throttled request (
429), which does not run the command at all.
When a command returns 202 and its job later fails, the command itself succeeded, so the key is spent. After you fix the cause, retry with a new key. See Async operations.
The supported automatic retry window is 24 hours. Retry within it and you get the saved result. Do not design a workflow that depends on a key being remembered beyond that.
Choosing keys
- Generate the key once, when you decide to perform the operation, and store it alongside your own record of the work. If your process crashes and restarts, it must send the same key.
- A random UUID works. A deterministic key built from your own record, such as
enroll-STUDENT_ID-SESSION_ID, also works and makes duplicates impossible by construction. - Never reuse a key for a different command body, even a small edit.
Retrying safely
Retry on network errors, 429, and 5xx responses, with the same key. Do not retry other 4xx responses without changing the request.
async function sendCommand(name, body, key) {
for (let attempt = 0; attempt < 5; attempt++) {
let response;
try {
response = await fetch("https://api.soljio.com/v0/commands/" + name, {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.SOLJIO_TOKEN,
"Content-Type": "application/json",
"Idempotency-Key": key,
},
body: JSON.stringify(body),
});
} catch {
await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 500));
continue;
}
if (response.status === 429) {
const seconds = Number(response.headers.get("Retry-After")) || 1;
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
continue;
}
if (response.status >= 500) {
await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 500));
continue;
}
return response;
}
throw new Error("Gave up after repeated failures");
}
Agents
Command tools on the MCP server take an optional idempotency_key argument. If an agent omits it, Soljio generates a new random key for the call, so a retry without a key is not protected. Agents that retry should pass the same idempotency_key each time. See Agents and MCP.
Troubleshooting
409 idempotency_conflict. You reused a key with different content. Either send the original content again, or choose a new key for the new operation.- A retry created a duplicate. The retry used a different key, a different command, or a different token. Keys match only within one school, token, API version, and command.
- The replay returned
403. The token no longer has the scopes the original request needed.