Idempotency and retries

Networks drop answers. When yours does, you want to send the request again without starting a second nest or spending a second solve. The Idempotency-Key header does that.

Send a key with every POST

Pick a value unique to the request, such as a UUID, and send it as a header with every POST to the API, and on the HTTP request that carries a tools/call to the MCP server:

POST /v1/nests HTTP/1.1
Authorization: Bearer <key>
Idempotency-Key: 7c3a1e4e-2b7a-4b0f-9d7e-3a2f6c1d8e90
Content-Type: application/json

The key may be 1 to 255 characters. A key outside that range is refused with 400.

What a retry gets

For a day after the first request, a POST with the same key to the same path with the same body gets the first answer again: the same status and body, marked with an idempotent-replayed: true header, with nothing new started and nothing counted against the workspace's budgets. The per-address budget still counts it, since it is checked on every request before anything else. A nest started once stays started once. On the MCP server a replay needs the same key, the same tool and the same arguments; the JSON-RPC id may differ.

Two answers tell you a retry met the first request in flight or mismatched it:

Status	Meaning
409	The first request with this key is still running. Wait, then send the same request again.
422	This key was used for a different request. Pick a new key.

Without a key

A POST without an Idempotency-Key runs every time it is sent. That is fine for a check or a quick linear solve you can afford to repeat, and wrong for anything that starts a job.

Retrying well

• Retry 409 after a short wait, with the same key and body.
• Retry 429 once the clock's minute turns; the budgets count per calendar minute. Keep the same key, so the retry is free if the first attempt did get through.
• Retry 500 and network failures with the same key.
• Do not retry 400, 401, 403, 413 or 422: the request itself has to change.