> ## 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.

# Errors and retries

> Every failure has a stable code and says what to do.

Every failure is an `OffstageError` with a `status`, a stable `code` (such as `sandbox-closed`, `bad-path` or `no-capacity`), a `message`, a `fix` that says what to do, and the plane's `requestId`. `isOffstageError(e)` tests for one.

```js theme={null}
import { isOffstageError } from "offstage-cloud"

try {
  await sandbox.commands.run("swift test")
} catch (e) {
  if (isOffstageError(e) && e.code === "sandbox-closed") {
    // create a new sandbox
  }
  throw e
}
```

Over HTTP every error has the same shape:

```json theme={null}
{ "error": { "code": "sandbox-closed", "message": "sandbox sbx_… is closed (idle)", "fix": "create a new sandbox", "requestId": "req_…" } }
```

Creates send an `Idempotency-Key` and retry network errors and 502, 503 and 504 answers, so a lost response never makes a second sandbox. A command is never started twice.

Every code is listed in the [Errors API reference](https://offstage.cloud/docs/api/errors.md).


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