Errors

Overview

All acp.cr errors inherit from ACP::Error, which itself inherits from Crystal's Exception. Errors are organized by category: transport, protocol, state, and request-level.

Error Hierarchy

ACP::Error

Base class for all acp.cr errors.

begin
  # any ACP operation
rescue ex : ACP::Error
  puts ex.message
end

ACP::TransportError

Transport-level failure (e.g., broken pipe, IO error).

rescue ex : ACP::TransportError
  puts "Transport failed: #{ex.message}"

ACP::ConnectionClosedError

The connection was closed unexpectedly.

rescue ex : ACP::ConnectionClosedError
  puts "Connection lost"

ACP::TransportTimeoutError

A transport-level operation timed out.

rescue ex : ACP::TransportTimeoutError
  puts "Transport timeout"

ACP::ProtocolError

A protocol-level issue occurred (e.g., malformed message).

rescue ex : ACP::ProtocolError
  puts "Protocol error: #{ex.message}"

ACP::VersionMismatchError

The agent's protocol version is incompatible.

rescue ex : ACP::VersionMismatchError
  puts "Version mismatch: #{ex.message}"

ACP::InvalidStateError

An operation was attempted in the wrong client state.

rescue ex : ACP::InvalidStateError
  puts "Invalid state: #{ex.message}"

ACP::JsonRpcError

A JSON-RPC 2.0 error was returned by the agent.

rescue ex : ACP::JsonRpcError
  puts "Error code: #{ex.code}"
  puts "Error message: #{ex.message}"

ACP::SessionNotFoundError

The referenced session does not exist.

rescue ex : ACP::SessionNotFoundError
  puts "Session not found"

ACP::NoActiveSessionError

An operation requiring an active session was attempted without one.

rescue ex : ACP::NoActiveSessionError
  puts "No active session"

ACP::AuthenticationError

Authentication with the agent failed.

rescue ex : ACP::AuthenticationError
  puts "Auth failed: #{ex.message}"

ACP::RequestTimeoutError

A request exceeded its timeout duration.

rescue ex : ACP::RequestTimeoutError
  puts "Request timed out"

ACP::RequestCancelledError

A request was cancelled before completion.

rescue ex : ACP::RequestCancelledError
  puts "Request cancelled"

Error Codes

Standard JSON-RPC 2.0 error codes and ACP-specific codes: