> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting

> Handle gateway failures, validation errors, and failed agent runs.

Use structured Agent SDK errors when your application needs to decide whether to retry, ask the user for different input, or show request details to an operator.

## Handle gateway failures

Gateway failures are rethrown as `AgentGatewayError`:

```typescript theme={null}
import { AgentGatewayError } from "@phaseo/agent-sdk";

try {
  await agent.run({ input, client });
} catch (error) {
  if (error instanceof AgentGatewayError) {
    console.error(error.status, error.requestId, error.reason);
  }
  throw error;
}
```

Failed runs and steps retain gateway error details when they are available.

## Handle schema failures

`AgentSchemaValidationError` identifies invalid tool input, tool output, progress events, or final output. Treat these as contract failures rather than transient model failures.

```typescript theme={null}
import { AgentSchemaValidationError } from "@phaseo/agent-sdk";

try {
  await agent.run({ input, client });
} catch (error) {
  if (error instanceof AgentSchemaValidationError) {
    console.error(error.target, error.message);
  }
  throw error;
}
```

## Inspect the failed run

When the runtime can checkpoint the failure, inspect:

* `result.run.status`
* `result.run.error`
* the latest step's `status`, `error`, and `modelAttempts`
* `requestId` and `nativeResponseId` for correlation with gateway logs

## Common checks

* Confirm `PHASEO_API_KEY` is available to the server process.
* Give each tool a unique, stable `id`.
* Use exact tool-call IDs when approving, rejecting, or supplying manual output.
* Keep model retries bounded; validation and approval failures should not retry blindly.
* Persist paused run state before returning control to a browser or queue worker.

## Related guides

* [Lifecycle hooks](./agent-sdk-lifecycle-hooks)
* [DevTools](./agent-sdk-devtools)
* [State and approval](./agent-sdk-state-and-approval)