---
title: "Error Handling"
description: "Structured errors that enable agents to diagnose failures and recover autonomously"
url: "https://agentsurface.dev/docs/error-handling"
lastVerified: 2026-09-24
lastModified: 2026-09-25T09:21:34.000Z
---



## Summary [#summary]

Error Handling covers structured failures that tell agents what happened and what to do next. Use it for HTTP errors, tool errors, CLI errors, retry policy, validation feedback, and idempotent recovery.

* **Owns:** RFC 9457 Problem Details, agent extensions, retry signals, idempotency keys, recovery suggestions, trace IDs, and CLI error contracts.
* **Does not own:** authentication flows themselves; see [Authentication](/docs/authentication). Tool naming and schemas; see [Tool Design](/docs/tool-design).
* **Agent-ready means:** the failure body is structured enough for the agent to retry, change input, switch tools, wait, or escalate without parsing prose.

## Start Here [#start-here]

* [RFC 9457](/docs/error-handling/rfc-9457) - Use Problem Details as the base error shape, plus agent extensions (retriable flags, suggestions, trace IDs, field errors).
* [Errors for Agents](/docs/error-handling/errors-for-agents) - Write failures as recovery contracts, not blame.
* [Retry Patterns](/docs/error-handling/retry-patterns) - Separate transient failures from terminal ones.
* [Idempotency](/docs/error-handling/idempotency) - Make write retries safe.
* [CLI Errors](/docs/error-handling/cli-errors) - Map command failures to structured output and stable exit codes.

## Related [#related]

* [API Surface](/docs/api-surface) - Expose error types as part of the HTTP contract.
* [CLI Design](/docs/cli-design) - Make command failures parseable and automatable.
* [Tool Design: Idempotency and Safety](/docs/tool-design/idempotency-and-safety) - Classify tool operations before retrying them.
* [Authentication](/docs/authentication) - Use structured auth failures instead of opaque 401/403 responses.
* [Testing](/docs/testing) - Verify recovery and retry behavior with evals and contract tests.