SDK errors | Aegis | Documentation

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.

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.

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:

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.

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 endpoint can legitimately take up to 300 seconds, so raise timeoutMs above that if you use it.