Errors

Stratus defines specific error classes for different failure modes. All errors extend StratusError.

Error Hierarchy

StratusError
├── MaxTurnsExceededError
├── MaxBudgetExceededError
├── RunAbortedError
├── ToolTimeoutError
├── ModelError
│   └── ContentFilterError
├── OutputParseError
├── InputGuardrailTripwireTriggered
└── OutputGuardrailTripwireTriggered

StratusError

Base class for all Stratus errors.

import { StratusError } from "@usestratus/sdk/core";

try {
  await run(agent, input);
} catch (error) {
  if (error instanceof StratusError) {
    console.error("Stratus error:", error.message);
  }
}

MaxTurnsExceededError

Thrown when the agent loop exceeds maxTurns without producing a final response.

import { MaxTurnsExceededError } from "@usestratus/sdk/core";

try {
  await run(agent, input, { maxTurns: 3 });
} catch (error) {
  if (error instanceof MaxTurnsExceededError) {
    console.error("Agent exceeded max turns");
  }
}

MaxBudgetExceededError

Thrown when the estimated cost of a run exceeds maxBudgetUsd. Requires a costEstimator in options. The onStop hook fires before this error is thrown.

import { MaxBudgetExceededError, createCostEstimator } from "@usestratus/sdk/core";

const estimator = createCostEstimator({
  inputTokenCostPer1k: 0.005,
  outputTokenCostPer1k: 0.015,
});

try {
  await run(agent, input, {
    costEstimator: estimator,
    maxBudgetUsd: 0.50,
  });
} catch (error) {
  if (error instanceof MaxBudgetExceededError) {
    console.error(`Budget exceeded: spent $${error.spentUsd.toFixed(4)} of $${error.budgetUsd.toFixed(4)}`);
  }
}

Properties:

budgetUsd: number - The budget limit that was set
spentUsd: number - The actual amount spent when the limit was crossed

RunAbortedError

Thrown when a run is cancelled via an AbortSignal. See Streaming - Abort Signal.

import { RunAbortedError } from "@usestratus/sdk/core";

const ac = new AbortController();
setTimeout(() => ac.abort(), 5000);

try {
  await run(agent, input, { signal: ac.signal });
} catch (error) {
  if (error instanceof RunAbortedError) {
    console.log("Run was cancelled");
  }
}

Pre-aborted signals throw RunAbortedError immediately without making any API calls.

ToolTimeoutError

Thrown when a tool exceeds its configured timeout. The run loop catches this internally and sends the error message back to the model as a tool result, so it does not propagate out of run().

import { ToolTimeoutError } from "@usestratus/sdk/core";

const slowTool = tool({
  name: "slow_search",
  description: "A slow search tool",
  parameters: z.object({ query: z.string() }),
  timeout: 5000, 
  execute: async (_ctx, { query }) => {
    return await slowExternalApi(query);
  },
});

Properties:

toolName: string - The name of the tool that timed out
timeoutMs: number - The timeout value in milliseconds

To customize the error message sent to the model, use a toolErrorFormatter in your run options.

ModelError

Thrown when the model API returns an error. Includes optional status and code fields:

import { ModelError } from "@usestratus/sdk/core";

try {
  await run(agent, input);
} catch (error) {
  if (error instanceof ModelError) {
    console.error(`Model error ${error.status}: ${error.message}`);
  }
}

ContentFilterError

A subclass of ModelError thrown when Azure's content filter blocks a request or response.

import { ContentFilterError } from "@usestratus/sdk/core";

try {
  await run(agent, input);
} catch (error) {
  if (error instanceof ContentFilterError) {
    console.error("Content was filtered by Azure");
  }
}

OutputParseError

Thrown when structured output fails to parse. See Structured Output.

InputGuardrailTripwireTriggered

Thrown when an input guardrail's tripwire fires. See Guardrails.

Properties:

guardrailName: string - Which guardrail fired
outputInfo?: unknown - Optional metadata from the guardrail

OutputGuardrailTripwireTriggered

Thrown when an output guardrail's tripwire fires. Same properties as the input variant.

On this page