Skip to content

fix(client): map JSON-RPC error bodies sent with a non-2xx HTTP status - #1476

Open
ArnabDutta01 wants to merge 1 commit into
a2aproject:mainfrom
ArnabDutta01:fix/F-a2a-python-001-jsonrpc-http-error-body
Open

ArnabDutta01 wants to merge 1 commit into
a2aproject:mainfrom
ArnabDutta01:fix/F-a2a-python-001-jsonrpc-http-error-body

Conversation

@ArnabDutta01

@ArnabDutta01 ArnabDutta01 commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

JsonRpcTransport now raises the mapped A2A error when a server sends a JSON-RPC error object with a non-2xx HTTP status, instead of a generic A2AClientError("HTTP Error 500: ...").

Fixes #1475

Rebased onto current main (c76e640). The only change to the PR's own code is for the httpx/httpx2 layer from #1439: the handler takes HTTPStatusError from a2a.utils._httpx_compat, like RestTransport._handle_http_error, and the new tests build their client with httpx_lib, so they also run in the httpx2 job (the test file is marked httpx2).

Root cause

_send_request and _send_stream_request passed no status_error_handler to the shared HTTP helpers:

response_data = await send_http_request(self.httpx_client, request)  # unary
...
send_http_stream_request(self.httpx_client, 'POST', self.url, None, self._handle_sse_error, ...)  # streaming

So for any non-2xx response, handle_http_exceptions (http_helpers.py#L40-L43) raised A2AClientError(f'HTTP Error {status}: ...') without reading the body. The JSON-RPC error code and the server's message were lost. RestTransport passes _handle_http_error (rest.py#L374-L390) and already reads error bodies on non-2xx responses.

This SDK's server always answers JSON-RPC errors with 200, but other servers don't. a2a-js sends HTTP 500 with a normal JSON-RPC error body for -32603 errors raised outside its main handler (json_rpc_handler.ts#L219-L220). Section 9.5 of the spec defines the error object, not the HTTP status.

Reproduction

httpx.MockTransport returns {"jsonrpc": "2.0", "id": "1", "error": {"code": -32603, "message": "database connection lost"}} for get_task. The full script is in #1475.

main, HTTP 200: InternalError: database connection lost
main, HTTP 500: A2AClientError: HTTP Error 500: Server error '500 Internal Server Error' for url 'http://agent'
this branch, HTTP 500: InternalError: database connection lost

Streaming does the same: a 404 with a -32001 body raised A2AClientError on main and raises TaskNotFoundError here.

Fix

Add JsonRpcTransport._handle_http_error and pass it in both places. It maps the body only when it is a JSON-RPC 2.0 error ("jsonrpc": "2.0", error is an object) whose code is a known A2A code. Mapping goes through the existing _create_jsonrpc_error, so ErrorInfo metadata in data is kept as it is at 200. Every other body raises the same A2AClientError(f'HTTP Error {status}: {e}') as before. That covers HTML from a proxy, a gateway's own {"error": {...}} (e.g. Google API style), an unknown or missing code, and non-JSON bodies. The original HTTPStatusError stays on __cause__.

The checks are narrow on purpose. Without them, a gateway's {"error": {"code": 429, ...}} or an unknown server code would replace today's "HTTP Error 429" with a "JSON-RPC Error ..." message and lose the status. Changing the shared handle_http_exceptions instead would push JSON-RPC parsing into code that REST also uses.

Impact on existing users

Only non-2xx responses whose body is a JSON-RPC 2.0 error with a known A2A code change. They now raise the mapped error (InternalError, TaskNotFoundError, ...) instead of A2AClientError. These classes subclass A2AError, not A2AClientError. So code that catches A2AClientError for such a response would no longer catch it, while except A2AError is unaffected. The same body at HTTP 200 already raises the mapped error, and so does RestTransport for its error format. Requests against this SDK's own server are unaffected, since it always uses 200.

Testing

Added TestJsonRpcErrorWithNonSuccessStatus in tests/client/transports/test_jsonrpc_client.py, using a real httpx_lib.AsyncClient with httpx_lib.MockTransport (httpx, or httpx2 when it is installed):

  • test_unary_maps_error_body[500-internal | 404-not-found]: get_task raises InternalError / TaskNotFoundError with the server's message.
  • test_streaming_maps_error_body: send_message_streaming with a 404 + -32001 body raises TaskNotFoundError.
  • test_other_bodies_raise_http_error, unary and streaming, a 502 with each body: HTML, non-JSON-RPC JSON, gateway {"error": {"code": 429, ...}}, JSON-RPC with unknown code -32050, JSON-RPC with error: {}. All still raise A2AClientError matching HTTP Error 502.

Same result with httpx and with httpx2 2.16.0:

$ pytest tests/client/transports/test_jsonrpc_client.py::TestJsonRpcErrorWithNonSuccessStatus   # main + new tests
FAILED ...::test_unary_maps_error_body[500-internal]
FAILED ...::test_unary_maps_error_body[404-not-found]
FAILED ...::test_streaming_maps_error_body
3 failed, 10 passed
$ pytest tests/client/transports/test_jsonrpc_client.py::TestJsonRpcErrorWithNonSuccessStatus   # this branch
13 passed

Python 3.12, dependencies installed from pyproject.toml, ruff 0.15.16 and ty 0.0.44 as in uv.lock:

  • ruff check, ruff format --check: pass. ty check: pass, with and without httpx2 installed (only the existing unused-suppression warnings, same as main, none in jsonrpc.py).
  • pytest --ignore=tests/integration/cross_version: 2663 passed, 215 skipped, 4 xfailed, 1 xpassed (main: 2650 passed, the other counts the same).
  • pytest -m httpx2 with httpx2 installed (same ignore): 1199 passed, 1 xpassed (main: 1186 passed).
  • pytest --cov=src --cov-fail-under=88 (same ignore): 93.9% total. All new lines and branches in jsonrpc.py are covered.

Not tested

  • tests/integration/cross_version: these tests need the uv binary to install older SDK versions, and I don't have it. The change doesn't touch the compat transports.
  • No live a2a-js server. The 500 response is reproduced with httpx.MockTransport, using the same body a2a-js builds.
  • Under --cov, test_on_message_send_stream in the two server request-handler test files sometimes fails on its elapsed < 0.5 timing assertion. It fails the same way on main and passes when run alone. Unrelated to this change.

Not changed here: src/a2a/compat/v0_3/jsonrpc_transport.py has its own _handle_http_error that discards the body in the same way (jsonrpc_transport.py#L421-L423). Happy to follow up there separately.

  • Follow the CONTRIBUTING Guide.
  • Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
  • Ensure the tests and linter pass (Run bash scripts/format.sh from the repository root to format)
  • Appropriate docs were updated (if necessary): no public API or docs change.

@ArnabDutta01
ArnabDutta01 requested a review from a team as a code owner November 15, 2026 21:19
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🧪 Code Coverage (vs main)

⬇️ Download Full Report

Base PR Delta
src/a2a/client/transports/http_helpers.py 93.51% 92.21% 🔴 -1.30%
src/a2a/client/transports/jsonrpc.py 95.51% 95.91% 🟢 +0.39%
src/a2a/server/cluster/database_event_stream.py 93.64% 97.27% 🟢 +3.64%
Total 93.79% 93.82% 🟢 +0.03%

Generated by coverage-comment.yml

JsonRpcTransport passed no status error handler to the shared HTTP
helpers, so a JSON-RPC error object sent with a non-2xx status (a2a-js
does this for internal errors) raised a generic "HTTP Error 500"
A2AClientError and dropped the error code and message.

Add JsonRpcTransport._handle_http_error, used by unary and streaming
requests. A JSON-RPC 2.0 error with a known A2A code now raises the
mapped error, as it already does with HTTP 200. Any other body keeps
raising the same generic HTTP error as before.

Signed-off-by: ArnabDutta01 <rickkdutta@gmail.com>
@ArnabDutta01
ArnabDutta01 force-pushed the fix/F-a2a-python-001-jsonrpc-http-error-body branch from 45430f9 to 70eb4b4 Compare November 19, 2026 09:46
@ArnabDutta01

Copy link
Copy Markdown
Author

@rohityan rebased onto current main. #1439 removed import httpx from jsonrpc.py, so the handler now takes HTTPStatusError from a2a.utils._httpx_compat, and the new tests use httpx_lib so they also run in the httpx2 job. No other changes; CI is green and it is ready for review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: JSON-RPC client ignores the JSON-RPC error body when the HTTP status is not 2xx

2 participants