Errors

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

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.