feat(rest): update REST error handling to use google.rpc.Status

[knapg]

Description

This PR refactors the REST transport error handling to adhere to the google.rpc.Status JSON format. Both the server-side exception handlers and the client-side REST transport have been updated to utilize the new standard error envelope, ensuring consistency across A2A REST APIs.

Summary of Changes

• Server:
  • Updated rest_error_handler and the global StarletteHTTPException handler in A2ARESTFastAPIApplication to return errors wrapped in an {'error': {...}} envelope.
  • Payloads now correctly include the HTTP code, gRPC status, message, and a details array containing type.googleapis.com/google.rpc.ErrorInfo for the specific reason and metadata.
• Client:
  • Modified RestTransport._handle_http_error to parse the new format. It now gracefully extracts the reason from the ErrorInfo detail object to map it back to the corresponding Python A2AError class.
• Core/Utils:
  • Introduced A2A_REST_ERROR_MAPPING in errors.py to centralize the mapping of Python exceptions to their respective HTTP status codes, gRPC statuses, and string reasons.
  • Added a data attribute to the base A2AError to carry arbitrary error metadata.
• Tests:
  • Updated REST client, server, and error handler tests to validate the new nested {'error': {...}} JSON payload structures.

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
  • Important Prefixes for release-please:
    • fix: which represents bug fixes, and correlates to a SemVer patch.
    • feat: represents a new feature, and correlates to a SemVer minor.
    • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
• Ensure the tests and linter pass (Run bash scripts/format.sh from the repository root to format)
• Appropriate docs were updated (if necessary)

Fixes #722 🦕

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! 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 robustness and consistency of error handling within the A2A REST API ecosystem. By adopting the AIP-193 standard for error responses, both server-side and client-side components now communicate errors in a unified, machine-readable format. This change improves interoperability, simplifies error diagnosis, and provides a clearer contract for how errors are structured and interpreted across the platform.

Highlights

• Standardized REST Error Format: Refactored REST transport error handling to conform to the AIP-193 google.rpc.Status JSON format, ensuring consistent error reporting across A2A REST APIs.
• Server-Side Error Handling: Updated the rest_error_handler and the global StarletteHTTPException handler to return errors within an {'error': {...}} envelope, including HTTP code, gRPC status, message, and ErrorInfo details.
• Client-Side Error Parsing: Modified RestTransport._handle_http_error to correctly parse the new AIP-193 format, extracting the reason from ErrorInfo to map to appropriate Python A2AError classes.
• Centralized Error Mapping and Metadata: Introduced A2A_REST_ERROR_MAPPING for centralized configuration of error responses and added a data attribute to the base A2AError to carry arbitrary error metadata.
• Comprehensive Test Updates: Updated REST client, server, and error handler tests to validate the new nested {'error': {...}} JSON payload structures.

Changelog

• src/a2a/client/transports/rest.py
  • Removed outdated error mapping logic.
  • Updated _handle_http_error to parse the new AIP-193 error format.
  • Extracted reason and metadata from error details to map to Python A2AError instances.
• src/a2a/server/apps/rest/fastapi_app.py
  • Imported StarletteHTTPException for global exception handling.
  • Defined a mapping for HTTP status codes to gRPC status strings.
  • Implemented a global StarletteHTTPException handler to format framework-level errors into the AIP-193 JSON format.
• src/a2a/utils/error_handlers.py
  • Removed old JSON-RPC error model imports and A2AErrorToHttpStatus mapping.
  • Updated rest_error_handler to use A2A_REST_ERROR_MAPPING for error response generation.
  • Modified error responses for A2AError, ParseError, and generic Exception to adhere to the AIP-193 format.
• src/a2a/utils/errors.py
  • Added a data attribute to the base A2AError class for carrying metadata.
  • Introduced A2A_REST_ERROR_MAPPING to centralize HTTP status, gRPC status, and reason mapping for A2AError types.
  • Updated A2A_ERROR_REASONS and A2A_REASON_TO_ERROR to derive from the new A2A_REST_ERROR_MAPPING.
• tests/client/transports/test_rest_client.py
  • Replaced JSON_RPC_ERROR_CODE_MAP with A2A_REST_ERROR_MAPPING in tests.
  • Updated test_rest_mapped_errors to assert against the new AIP-193 error payload structure.
• tests/server/apps/rest/test_rest_fastapi_app.py
  • Added a new test case to verify global HTTP exceptions are formatted as per AIP-193.
• tests/utils/test_error_handlers.py
  • Removed A2AErrorToHttpStatus import.
  • Updated MockJSONResponse to support media_type assertion.
  • Modified test assertions for rest_error_handler to expect the new AIP-193 error structure.
  • Removed the test_a2a_error_to_http_status_mapping test.

Activity

• No specific activity (comments, reviews, progress) has been recorded for this pull request yet.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request 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

1. 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. ↩

[gemini-code-assist]

Code Review

This pull request is an excellent refactoring of the REST error handling to conform to the AIP-193 google.rpc.Status standard. The changes are comprehensive, touching the client, server, and utility code to ensure consistency. The introduction of A2A_REST_ERROR_MAPPING centralizes error information, greatly improving maintainability. The server-side exception handlers are now standardized, and the client is updated to parse the new error format. The accompanying tests are thorough and correctly validate the new behavior. I have one minor suggestion to improve the consistency of logging.

[knapg]

@check-spelling-bot apply updates

[ishymko]

I am afraid #838 (comment) doesn't work, we usually just add unknown words to allow.txt.

Currently it complains about AIP:

[github-actions]

🧪 Code Coverage (vs 1.0-dev)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/client/transports/rest.py	92.41%	91.52%	🔴 -0.90%
src/a2a/server/apps/rest/fastapi_app.py	80.95%	81.25%	🟢 +0.30%
src/a2a/utils/error_handlers.py	91.67%	93.33%	🟢 +1.67%
Total	89.94%	89.94%	⚪️ 0.00%

Generated by coverage-comment.yml