The Agent Communication Protocol (ACP) provides a consistent error structure to make error handling easier for both clients and servers.

​
Error structure

Each error contains:
  • Code: A predefined identifier for programmatic handling
  • Message: A human-readable description for display or logging
Use codes to drive error-handling logic and messages for user display or logging. See the specification for the current set of error codes.

​
Error handling

Servers can send errors in three ways:
  • HTTP response body (failed requests)
  • Within a failed run
  • As events in a stream error
Clients must monitor all these locations and handle errors appropriately. SDK clients should expose errors in a way that’s natural for the programming language, typically as exceptions: 
try:
    run = await client.run_sync(...)
    run.raise_for_status()
except ACPError as e:
    error = e.error
    # Logic that handles the error

​
Guidance

When handling errors:
  • Use the code for programmatic decisions
  • Use the message for display or logging
  • Tailor your response to your application type
Example: A chat UI should show invalid_input error messages to users, but log server_error messages to the console (since they may be too technical). A CLI would likely display all error messages regardless of code.