Error Handling

Error Types

Agent Errors

Error	When	Recovery
AgentError	General agent failure	Check stepId for context
ToolError	A tool throws during execution	Check toolName, fix tool handler
MaxStepsError	ReAct loop hit maxSteps	Increase maxSteps or simplify the task

Client Errors

Error	When	Recovery
SchiftError	API call failed	Check status and code
AuthError	Invalid API key (401)	Verify your sch_... key
QuotaError	Usage limit exceeded (402)	Upgrade plan or wait for reset

Catching Agent Errors

import { AgentError, MaxStepsError } from "@schift-io/sdk";

try {
  const result = await agent.run("Complex question");
} catch (err) {
  if (err instanceof MaxStepsError) {
    console.log("Agent took too many steps. Try a simpler question.");
  } else if (err instanceof AgentError) {
    console.log(`Agent error at step ${err.stepId}: ${err.message}`);
  }
}

Max Steps

The default maxSteps is 10. If your agent needs more tool calls, increase it:

const agent = new Agent({
  maxSteps: 25,  // Allow up to 25 ReAct iterations
  ...
});

When maxSteps is reached, agent.run() returns with the error message as output (does not throw). Check result.steps for the last step’s type:

const result = await agent.run("...");
const lastStep = result.steps[result.steps.length - 1];

if (lastStep.type === "error") {
  console.log("Agent did not reach a final answer");
}

Tool Error Handling

Tool handler errors are caught and returned to the LLM. The agent sees the error and can decide to retry or use a different approach.

const riskyTool: AgentTool = {
  name: "risky_api",
  description: "Call an unreliable API",
  handler: async (args) => {
    try {
      const data = await callUnreliableAPI(args);
      return { success: true, data };
    } catch (err) {
      return {
        success: false,
        data: null,
        error: err.message,
      };
    }
  },
};

API Client Errors

import { SchiftError, AuthError, QuotaError } from "@schift-io/sdk";

try {
  const results = await rag.search("query");
} catch (err) {
  if (err instanceof AuthError) {
    console.log("Check your API key");
  } else if (err instanceof QuotaError) {
    console.log("Quota exceeded -- upgrade your plan");
  } else if (err instanceof SchiftError) {
    console.log(`API error: ${err.status} ${err.code}`);
  }
}