---
title: Idempotency
description: 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.

```http
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](/developers/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 `data` and the original status, including `201` or `202` and the `Location` header,
- the original `request_id` in the body,
- `"idempotent_replay": true`,
- a fresh `X-Request-Id` header that identifies this attempt.

Nothing is written again. Queued jobs are not queued again, and no second success audit entry is recorded.

```json
{
  "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](/developers/rate-limits).

## 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 (`409` `conflict`),
- 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](/developers/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.

```js
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](/developers/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.
