fix(spec): Adding a comprehensive error handling description for gRPC and … #976
Conversation
…HTTP+JSON transports to ensure functional equivalence across all A2A transport protocols
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @maeste, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the A2A specification by adding comprehensive documentation for error handling across gRPC and HTTP+JSON transport protocols. The primary goal is to ensure consistent error semantics and functional equivalence with the existing JSON-RPC 2.0 error handling. This update provides clear guidelines, mapping tables, and structural definitions for how errors should be reported, making the A2A protocol more robust and predictable for implementers and clients across various communication methods.
Highlights
- New Error Handling Principles: The documentation now includes a dedicated section on general error handling principles, emphasizing transport equivalence, error code consistency, structured error information, and security considerations for A2A-compliant implementations.
- Comprehensive gRPC Error Handling: Detailed specifications for gRPC error handling have been added, including mappings for standard gRPC status codes to common A2A error conditions and specific mappings for A2A-defined errors. It also outlines the structure for providing detailed error information using
google.rpc.Status. - Detailed HTTP+JSON/REST Error Handling: The PR introduces a thorough guide for HTTP+JSON/REST error handling, covering the use of appropriate HTTP status codes, A2A-specific error mappings, a consistent JSON response format for errors, and recommended HTTP error headers.
- Unified Cross-Transport Error Mapping: A new cross-transport error mapping table has been added, providing a clear, comprehensive overview of how A2A error conditions are represented across JSON-RPC, gRPC, and HTTP protocols. This ensures functional equivalence and predictability for clients.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive and well-structured error handling section to the specification, covering gRPC and HTTP+JSON transports to ensure functional equivalence with JSON-RPC. The new sections are detailed and the cross-transport mapping table is excellent for promoting consistency across implementations.
I've added a couple of suggestions to further improve the consistency of the HTTP error format with the gRPC error model and to clarify the mapping table for transport-level errors. Overall, this is a great enhancement to the protocol specification.
maeste
changed the title
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
maeste
changed the title
maeste
force-pushed
the
maeste/issue975
branch
from
0e0f8d7 to
f138a48
Compare
holtskinner
changed the title
| // --8<-- [start:JSONError] | ||
| /** | ||
| * Represents the error format for HTTP+JSON/REST transport error responses. | ||
| */ | ||
| export interface JSONError { | ||
| /** A2A-specific error identifier (e.g., "TASK_NOT_FOUND"). */ | ||
| code: string; | ||
| /** Human-readable error description. */ | ||
| message: string; | ||
| /** Optional additional structured error information. */ | ||
| details?: any; | ||
| } | ||
| // --8<-- [end:JSONError] |
There was a problem hiding this comment.
Not sure if I missed this on my earlier review. Is there a reason to have another type here in addition to the A2AError? Should JSONError be an extension of or contain an A2AError instance?
There was a problem hiding this comment.
It maps generic json-rpc errors (iow ones in 8.1 in the spec) while a2aerrror maps specific a2A (the ones in 8.2 in the spec). They are different kind of error and I think is more clear this way
There was a problem hiding this comment.
@holtskinner does my previous comment make sense to you?
|
It maps generic json-rpc errors (iow ones in 8.1 in the spec) while
a2aerrror maps specific a2A (the ones in 8.2 in the spec). They are
different kind of error and I think is more clear this way
Il gio 21 ago 2025, 19:08 Holt Skinner ***@***.***> ha
scritto:
… ***@***.**** requested changes on this pull request.
------------------------------
In types/src/types.ts
<#976 (comment)>:
> +// --8<-- [start:JSONError]
+/**
+ * Represents the error format for HTTP+JSON/REST transport error responses.
+ */
+export interface JSONError {
+ /** A2A-specific error identifier (e.g., "TASK_NOT_FOUND"). */
+ code: string;
+ /** Human-readable error description. */
+ message: string;
+ /** Optional additional structured error information. */
+ details?: any;
+}
+// --8<-- [end:JSONError]
Not sure if I missed this on my earlier review. Is there a reason to have
another type here in addition to the A2AError? Should JSONError be an
extension of or contain an A2AError instance?
—
Reply to this email directly, view it on GitHub
<#976 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAASDUUNUY662LVMZJ264HD3OX4KNAVCNFSM6AAAAACDW7EQ6SVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTCNBRGU4TKNRSGE>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
…HTTP+JSON transports to ensure functional equivalence across all A2A transport protocols
Description
Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
CONTRIBUTINGGuide.nox -s formatfrom the repository root to format)Fixes #975 🦕