Errors

The SDK throws typed errors so you can branch on failure modes.

`AmikaError`

The base class for every error the SDK raises.

class AmikaError extends Error {}

Catch AmikaError to handle anything the SDK throws. The SDK throws a plain AmikaError for invalid client options, an empty hostId, invalid service ports, and failed or timed-out snapshot waits.

`AmikaHTTPError`

Thrown when the API returns a non-2xx response.

class AmikaHTTPError extends AmikaError {
  readonly statusCode: number;
  readonly body: string;
  userMessage(): string;
}

statusCode: the HTTP status.
body: the raw response body.
userMessage(): parses a structured error ({ code | error_code, message }) from the body and returns a readable string, prefixed with the stable error code when there is one. Falls back to the raw body if parsing fails.

`AmikaWaitError`

Thrown by rig.wait() and client.rigs.getAndWait() when a rig can’t reach the requested state.

class AmikaWaitError extends AmikaError {
  readonly reason: "provisioning" | "setup" | "timeout";
  readonly rigId: string;
  readonly status: string;
  readonly state: string;
  readonly setupStatus: string | undefined;
}

reason: provisioning if the rig failed, setup if its setup script failed, or timeout if the deadline passed.
rigId, status, state, setupStatus: the last observed rig state. rigId is empty if the first fetch never completed.

Handling errors

import { AmikaHTTPError, AmikaWaitError } from "@amika/sdk";

try {
  await client.rigs.getAndWait("dev-box", { maxWaitMs: 120_000 });
} catch (err) {
  if (err instanceof AmikaWaitError) {
    console.error(err.reason, err.status, err.setupStatus);
  } else if (err instanceof AmikaHTTPError) {
    console.error(err.statusCode);      // e.g. 404
    console.error(err.userMessage());   // readable message
  } else {
    throw err;
  }
}

Agent failures

A failed agent turn is not an exception. send() and sendStream() return isError: true with details in response, even when the HTTP request succeeds. If the agent’s credential is the problem, fix the injected credential. See Inject credentials.

const turn = await rig.send({ message: "Run the test suite" });
if (turn.isError) {
  console.error("Agent failed:", turn.response);
}

Overview

TypeScript

`AmikaError`

`AmikaHTTPError`

`AmikaWaitError`

Handling errors

Agent failures

​AmikaError

​AmikaHTTPError

​AmikaWaitError

​Handling errors

​Agent failures

`AmikaError`

`AmikaHTTPError`

`AmikaWaitError`

Handling errors

Agent failures