Errors

The SDKs raise a small set of error types, so you can branch on the type rather than parse a message. All of them extend AuraError, so one catch covers everything.

Type	Means	Carries
AuraApiError	The API rejected the call	status, detail
AuraConnectionError	Nothing answered — the request never reached a server (TypeScript only)	url, code
AuraResponseError	The server answered, but with something the SDK could not read	status — always in Python, when known in TypeScript
AuraTurnCancelledError	The turn stopped before finishing	the partial content, the conversation id
AuraTurnTimeoutError	Your wait elapsed — the turn is still running	the project id, the conversation id, the elapsed wait, the partial

A rejected request

Any non-2xx response. status is the HTTP code; detail is the API’s error body, which is a string for simple errors, an object for structured ones, and a list for a 422 validation error — check before assuming a shape.

TypeScript

import { AuraApiError } from "@strangeworks-inc/strangeworks-aura-sdk";

try {
  await aura.getProject(projectId);
} catch (err) {
  if (err instanceof AuraApiError) {
    if (err.status === 401) throw new Error("key missing or revoked");
    if (err.status === 404) return null;               // no such project
    if (err.status === 429) return retryLater();       // rate limited
  }
  throw err;
}

Python

from aura_sdk import AuraApiError

try:
    await aura.get_project(project_id)
except AuraApiError as err:
    if err.status == 401:
        raise RuntimeError("key missing or revoked") from err
    if err.status == 404:
        return None
    if err.status == 429:
        return await retry_later()
    raise

An unreachable host

AuraConnectionError means the request never reached a server at all — connection refused, a DNS miss, a TLS failure. url is the address that was tried and code is the OS-level reason (ECONNREFUSED, ENOTFOUND, …) when the runtime exposes one.

The url is the request’s own target, not the client’s base URL: a byte upload goes to a storage host the base URL does not name, and that host is the one worth reporting.

TypeScript

import { AuraConnectionError } from "@strangeworks-inc/strangeworks-aura-sdk";

try {
  await aura.listProjects();
} catch (err) {
  if (err instanceof AuraConnectionError) {
    throw new Error(`Aura is unreachable at ${err.url} (${err.code ?? "no code"})`);
  }
  throw err;
}

Python

import httpx

try:
    await aura.list_projects()
except httpx.ConnectError as err:
    raise RuntimeError(f"Aura is unreachable: {err}") from err

Why only TypeScript has this type

httpx already raises a precise, well-named ConnectError, so the Python SDK lets it through rather than hiding it behind a type of our own — as it does every httpx.TransportError, an elapsed request timeout (httpx.ReadTimeout) included. JavaScript’s fetch gives an opaque TypeError: fetch failed instead, which says nothing about what went wrong — so the TypeScript SDK translates it.

An unreadable response

AuraResponseError means the call reached Aura and came back, but the body was not what the contract promises — an empty body where one was required, or a payload that is not the JSON it claimed. It is distinct from AuraApiError, which is the API deliberately rejecting you.

In TypeScript status is set only when it is known, so check it rather than assume; in Python it always is.

A turn that stopped

Raised when the server marked the reply partial: the turn was cancelled — by you, by another caller, or in TypeScript by aborting the signal — or died before finishing. Whatever the agent produced is attached. In Python, cancelling the task that awaits chat() raises asyncio.CancelledError instead, and leaves the turn running.

TypeScript

import { AuraTurnCancelledError } from "@strangeworks-inc/strangeworks-aura-sdk";

try {
  const reply = await aura.chat(project.id, "Solve this.", { signal });
  return reply.content;
} catch (err) {
  if (err instanceof AuraTurnCancelledError) {
    return err.partialContent ?? "(the agent stopped before writing anything)";
  }
  throw err;
}

Python

from aura_sdk import AuraTurnCancelledError

try:
    reply = await aura.chat(project.id, "Solve this.")
    return reply.content
except AuraTurnCancelledError as cancelled:
    return cancelled.partial_content or "(the agent stopped before writing anything)"

A wait that elapsed

A timeout does not stop the turn

chat() gives up waiting after fifteen minutes by default; the agent keeps working server-side. Wait longer, poll on your own schedule, or cancel. A solve can outlast fifteen minutes — raise the timeout for those rather than re-sending the message.

It is never a turn that already finished: before raising, chat() reads the turn’s state back from the server, so a reply that landed while the stream was silent is returned rather than reported as a timeout. partialContent / partial_content carries whatever the turn had streamed.

TypeScript

import { AuraTurnTimeoutError } from "@strangeworks-inc/strangeworks-aura-sdk";

try {
  return await aura.chat(project.id, "Solve this.", { timeoutMs: 10 * 60_000 });
} catch (err) {
  if (err instanceof AuraTurnTimeoutError) {
    console.warn(`still running after ${String(err.timeoutMs)}ms`);
    await aura.cancel(project.id, err.conversationId);   // or keep polling instead
  }
  throw err;
}

Python

from aura_sdk import AuraTurnTimeoutError

try:
    return await aura.chat(project.id, "Solve this.", timeout=10 * 60)
except AuraTurnTimeoutError as timed_out:
    print(f"still running after {timed_out.timeout}s")
    await aura.cancel(project.id, timed_out.conversation_id)   # or keep polling
    raise

The elapsed wait is in milliseconds in TypeScript (timeoutMs) and seconds in Python (timeout).

Catching everything

TypeScript

import { AuraError } from "@strangeworks-inc/strangeworks-aura-sdk";

try {
  await runPipeline();
} catch (err) {
  if (err instanceof AuraError) {
    console.error(`Aura: ${err.name}: ${err.message}`);
  }
  throw err;
}

Python

from aura_sdk import AuraError

try:
    await run_pipeline()
except AuraError as err:
    logger.exception("Aura call failed: %s", type(err).__name__)
    raise

In the CLI

Anything you are expected to hit prints as a plain message and exits 1 — a rejected request, an unreachable host, a mistyped flag, a missing setting. No stack traces. Each says what happened on the first line, and how to fix it on the second where the CLI knows:

$ aura project list
error Could not reach http://localhost:3000 (ECONNREFUSED)
Check that the server is running and that AURA_BASE_URL (or --base-url) points at it.

$ aura project list
error 401 Invalid API key
Check AURA_API_KEY (or --api-key). A key is per company and per region — mint one under
Settings → API Keys in the app for the region you are targeting.
That request went to https://aura-api-eu.strangeworks.com (the default region).
Use --region (eu or us), or --base-url, to target a different one.

$ aura conversation list --project 00000000-0000-0000-0000-000000000000
error 404 Project not found
Check the id. The matching "aura <noun> list" command shows what exists.

The first line is the API’s own detail — the same string the SDKs put on AuraApiError.detail. Where that already names its remedy (a 409 reads “a turn is in flight on this project — wait for it to finish, then retry”), the CLI adds nothing under it.

Cancelling a turn with Ctrl-C during aura chat --message stops the turn server-side and exits 130.

A stack trace means something else: the CLI hit a case it does not recognise, which is a bug worth reporting. It says so, and the trace is what to include.