Skip to main content
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.