> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aegi.run/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aegi.run/_mcp/server.

# SDK errors

## One error class

Every failure — a rejected request, a dropped connection, a missing path
parameter — arrives as an `AegisError`. There is no subclass hierarchy, so
branch on `status` or `code`.

```ts
import { AegisError } from 'aegis-api'

try {
  await aegis.music.play(guildId, { query: 'lofi' })
} catch (error) {
  if (error instanceof AegisError) {
    error.status // HTTP status, or 0 if the request never left
    error.code // 'forbidden', 'rate_limited', ...
    error.message // the API's message, or the transport error's
    error.requestId // quote this when asking for help
    error.body // the parsed error envelope, if there was one
  }
}
```

## What maps to what

| Situation                                                    | `status`        | `code`                         |
| ------------------------------------------------------------ | --------------- | ------------------------------ |
| The API rejected the request                                 | the real status | `error.code` from the envelope |
| The API answered non-2xx with an unrecognised body           | the real status | `internal_error`               |
| `fetch` itself threw — DNS, TLS, timeout                     | `0`             | `service_unavailable`          |
| A `{placeholder}` path parameter was not supplied            | `0`             | `bad_request`                  |
| The client was constructed with no `apiKey` and no `baseUrl` | `0`             | `bad_request`                  |

A `status` of `0` always means the request never reached Aegis. Nothing about it
is worth retrying immediately without checking your own setup first.

> **Note**
>
> The missing-path-parameter case rejects rather than throws synchronously — it
> happens inside the async request pipeline. Only the constructor guard throws
> immediately.

## Reacting to specific failures

Rate limiting and player limits are the two worth special-casing, since both
have a correct response other than giving up:

```ts
import { AegisError } from 'aegis-api'

async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
  for (;;) {
    try {
      return await fn()
    } catch (error) {
      if (!(error instanceof AegisError) || error.status !== 429) throw error

      // error.body is the parsed envelope; Retry-After is on the response
      // headers, which are not retained, so back off conservatively.
      await new Promise((r) => setTimeout(r, 1000))
    }
  }
}
```

`player_limit` means the project is at its concurrent-player ceiling for the
plan — back off, or upgrade. See [rate limits](/rate-limits).

## What is not an error

A `200` response carrying a failure inside the body is not raised. The binary
encode and decode endpoints do this: a decode failure comes back as
`{ error: true, data: { error: '…' } }`. Read `data.error` on those.

`aegis.music.meaning` behaves similarly, resolving with `meaning: null` when
nothing was found.

## Timeout

The default timeout is 30 seconds, overridable per client with `timeoutMs`. A
timeout surfaces as an `AegisError` with `status: 0`. The
[`aegis.jobs.wait`](/jobs) endpoint can legitimately take up to 300 seconds, so
raise `timeoutMs` above that if you use it.