> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Idempotency

> Retry a create safely with an Idempotency-Key.

Send `Idempotency-Key: <any unique string, 1 to 255 characters>` on `POST /v1/sandboxes` and `POST /v1/tasks`. This lets you retry a create whose answer you never got, after a timeout, a dropped connection or a 502/503/504, without making a second sandbox or task.

* The same key and the same body within 24 hours answers with what the first request made: `201`, the same id, the record as it is now (a task may have started or ended since), and an `idempotent-replayed: true` header. This holds across a plane restart.
* If that task has since been dropped from the records (each team keeps a bounded share), the key is 409 `idempotency-key-spent` for the rest of its 24 hours. Use a new key to make another.
* The same key with a different body is 409 `idempotency-key-reused`.
* A retry that arrives while the first request is still running is 409 `idempotency-key-in-use`. Retry it again shortly.
* Failures are not remembered. A create refused with 402 can be retried with the same key after the cause is fixed.
* Keys are scoped to your team and to the route.

The JavaScript SDK sends a fresh key with every create and reuses it on its own retries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.