Repository navigation
fix(client): map JSON-RPC error bodies sent with a non-2xx HTTP status - #1476
Open
ArnabDutta01 wants to merge 1 commit into
Open
ArnabDutta01 wants to merge 1 commit into
ArnabDutta01 wants to merge 1 commit into
Conversation
🧪 Code Coverage (vs
|
| 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
force-pushed
the
fix/F-a2a-python-001-jsonrpc-http-error-body
branch
from
November 19, 2026 09:46
45430f9 to
70eb4b4
Compare
Author
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
JsonRpcTransportnow raises the mapped A2A error when a server sends a JSON-RPC error object with a non-2xx HTTP status, instead of a genericA2AClientError("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 takesHTTPStatusErrorfroma2a.utils._httpx_compat, likeRestTransport._handle_http_error, and the new tests build their client withhttpx_lib, so they also run in the httpx2 job (the test file is markedhttpx2).Root cause
_send_requestand_send_stream_requestpassed nostatus_error_handlerto the shared HTTP helpers:So for any non-2xx response,
handle_http_exceptions(http_helpers.py#L40-L43) raisedA2AClientError(f'HTTP Error {status}: ...')without reading the body. The JSON-RPC error code and the server's message were lost.RestTransportpasses_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
-32603errors 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.MockTransportreturns{"jsonrpc": "2.0", "id": "1", "error": {"code": -32603, "message": "database connection lost"}}forget_task. The full script is in #1475.Streaming does the same: a 404 with a
-32001body raisedA2AClientErroronmainand raisesTaskNotFoundErrorhere.Fix
Add
JsonRpcTransport._handle_http_errorand pass it in both places. It maps the body only when it is a JSON-RPC 2.0 error ("jsonrpc": "2.0",erroris an object) whosecodeis a known A2A code. Mapping goes through the existing_create_jsonrpc_error, soErrorInfometadata indatais kept as it is at 200. Every other body raises the sameA2AClientError(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 originalHTTPStatusErrorstays 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 sharedhandle_http_exceptionsinstead 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 ofA2AClientError. These classes subclassA2AError, notA2AClientError. So code that catchesA2AClientErrorfor such a response would no longer catch it, whileexcept A2AErroris unaffected. The same body at HTTP 200 already raises the mapped error, and so doesRestTransportfor its error format. Requests against this SDK's own server are unaffected, since it always uses 200.Testing
Added
TestJsonRpcErrorWithNonSuccessStatusintests/client/transports/test_jsonrpc_client.py, using a realhttpx_lib.AsyncClientwithhttpx_lib.MockTransport(httpx, or httpx2 when it is installed):test_unary_maps_error_body[500-internal | 404-not-found]:get_taskraisesInternalError/TaskNotFoundErrorwith the server's message.test_streaming_maps_error_body:send_message_streamingwith a 404 +-32001body raisesTaskNotFoundError.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 witherror: {}. All still raiseA2AClientErrormatchingHTTP Error 502.Same result with httpx and with httpx2 2.16.0:
Python 3.12, dependencies installed from
pyproject.toml,ruff0.15.16 andty0.0.44 as inuv.lock:ruff check,ruff format --check: pass.ty check: pass, with and without httpx2 installed (only the existing unused-suppression warnings, same asmain, none injsonrpc.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 httpx2with 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 injsonrpc.pyare covered.Not tested
tests/integration/cross_version: these tests need theuvbinary to install older SDK versions, and I don't have it. The change doesn't touch the compat transports.httpx.MockTransport, using the same body a2a-js builds.--cov,test_on_message_send_streamin the two server request-handler test files sometimes fails on itselapsed < 0.5timing assertion. It fails the same way onmainand passes when run alone. Unrelated to this change.Not changed here:
src/a2a/compat/v0_3/jsonrpc_transport.pyhas its own_handle_http_errorthat discards the body in the same way (jsonrpc_transport.py#L421-L423). Happy to follow up there separately.CONTRIBUTINGGuide.bash scripts/format.shfrom the repository root to format)