Errors and retries

The SDK distinguishes input validation failures, HTTP errors, transport failures, timeouts and cancellation. Wrap both the method call and its await in try/catch: some validation happens before a promise is returned.

Handle errors

import { TimeoutError } from '@emby-chat/node-sdk';

try {
  await emby.sendMessage(
    'support-42',
    { id: 'u-1', name: 'Alice' },
    [],
    'Hello',
  );
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error('Request timed out', error.code);
  } else if (error instanceof Error && 'status' in error) {
    const response = error as Error & { status: number; body: unknown };
    console.error(response.status, response.body);
  } else {
    throw error;
  }
}

Failure	Error
Invalid generated API input	ZodError, before the HTTP request
Invalid convenience-method input	A plain Error with a descriptive message
HTTP error	Error carrying status, parsed body and response headers
Attempt timeout	TimeoutError, with code: 'ETIMEDOUT'
Caller cancellation	The signal's abort reason, or AbortError

Successful responses are passed through, so also inspect application-level fields such as status where the endpoint uses them.

Configure defaults

import { Emby } from '@emby-chat/node-sdk';

const emby = new Emby({
  api_token: process.env.EMBY_API_TOKEN,
  api_url: 'https://api.getchat.io',
  options: { timeout: 5_000, retries: 2, retryDelay: 200 },
});

Defaults are 30,000 ms per attempt, 2 retry attempts after the first attempt, and a base retry delay of 200 ms. Set timeout: 0 to disable the per-attempt timeout or retries: 0 to disable retries.

GET and DELETE requests retry transport failures, HTTP 429, and HTTP 500, 502, 503 or 504. POST and PUT retry HTTP 429 and connection failures that establish the request was not sent. A write that times out is not automatically repeated.

Backoff grows exponentially with jitter. When present, Retry-After determines the wait; waits are capped at 30 seconds. A timed-out read can take about (retries + 1) × timeout, plus backoff.

Override one call or cancel a walk

const result = await emby.api.chatShow({
  path: { chat_id: 'support-42' },
  timeout: 5_000,
  retries: 0,
  signal: AbortSignal.timeout(10_000),
});

timeout, retries, retryDelay and signal go at the top level of generated method inputs, in iterator query objects, or in the seventh argument of requestApi(). They are not sent to the API. Convenience methods without these arguments use the client defaults.

A signal can bound the complete call, including retries. Cancelling also interrupts backoff; cancelled requests are not retried.

See EmbyRequestOptions, RequestControlOptions and TimeoutError.