A2A Error Handling

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for the error handling section
2. Web-search site:github.com a2aproject A2A error codes for error code definitions
3. Web-search site:github.com a2aproject a2a-samples error for error handling examples
4. Fetch SDK docs for error classes and exception types

Conceptual Architecture

Error Categories

A2A has three categories of errors:

1. JSON-RPC Protocol Errors — Malformed requests, invalid methods, parse failures
2. A2A-Specific Errors — Protocol-level issues specific to A2A operations
3. Task-Level Failures — The task itself fails during processing (task state → failed)

JSON-RPC 2.0 Error Format

All errors follow the JSON-RPC 2.0 error response format:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": { "details": "..." }
  }
}

Standard JSON-RPC Error Codes

A2A-Specific Error Codes

Task Failure vs Protocol Error

Important distinction:

• Protocol errors return a JSON-RPC error response — the request itself was invalid or couldn't be processed
• Task failures return a normal response with the task in failed state — the request was valid but the task's processing failed

Example: If a client sends message/send with invalid JSON → -32700 (protocol error). If a client sends a valid message but the agent's LLM call fails → task state becomes failed with an error message.

Server-Side Error Handling

The server should:

1. Validate JSON-RPC structure — Return -32600/-32700 for malformed requests
2. Validate method — Return -32601 for unsupported methods
3. Validate parameters — Return -32602 for invalid params
4. Check task existence — Return -32001 for unknown task IDs
5. Check capabilities — Return -32003/-32005 for unsupported features
6. Handle extended card — Return -32007 if extended Agent Card is not configured
7. Handle internal errors — Return -32603 for unexpected server errors
8. Set task state — Transition to failed for task-level processing errors

Client-Side Error Handling

The client should:

1. Parse the response — Check for error field vs result field
2. Handle by error code — Different codes need different responses
3. Retry transient errors — -32603 (internal error) may be retryable
4. Don't retry permanent errors — -32601 (method not found) won't succeed on retry
5. Handle task failures — Check task state for failed and read the error message
6. Fallback — Try alternative agents if one fails

Retry Strategy

Best Practices

• Always include meaningful error messages, not just codes
• Use the data field in JSON-RPC errors for additional debugging context
• Log errors with request IDs and task IDs for traceability
• Implement circuit breakers for agents that are consistently failing
• Set task state to failed with a descriptive message when processing fails
• Don't expose internal implementation details in error messages to external clients
• Implement graceful degradation — if one agent in a pipeline fails, handle it upstream
• Test error paths explicitly — they're as important as the happy path

Fetch the specification for the complete list of error codes, their semantics, and any error handling requirements before implementing.