http: surface the server's error body on failed calls and discovery

Merged
H3
2mo ago
+272-4

Summary

Python counterpart of universal-tool-calling-protocol/typescript-utcp#44 (which lands typescript-utcp#26), so both SDKs surface the server's error body in the same release.

raise_for_status() raises a ClientResponseError whose message is only the reason phrase (Forbidden). Servers put the real reason in the body, typically {"error": "..."}, and that was discarded, so a refused call or discovery surfaced as nothing more than a status code.

Change: a new raise_for_status_with_body helper reads the body on a 4xx/5xx and raises a ClientResponseError of the same status and headers whose message is <reason>: <detail>. detail is a string error / message / detail field when the body is a JSON object (an object-valued field falls through to the raw JSON so its structure shows, matching the TypeScript behavior), otherwise the raw body, truncated to 2000 characters. The raw text is attached as .body. Used by the HTTP protocol's tool calls and discovery, and by SSE and Streamable HTTP discovery.

The exception type is unchanged, so existing except ClientResponseError handlers keep working; they just see a more useful message.

Test plan

  • New tests: body in the tool-call error, object-valued error field shows INVALID_FIELD / value out of range, discovery errors[] carries the body for HTTP, SSE and Streamable HTTP
  • pytest plugins/communication_protocols/http/tests: 213 passed

šŸ¤– Generated with Claude Code


Summary by cubic

Surfaces the server's error body on failed HTTP calls and discovery so errors include the real reason from the response instead of just the status code.

Bug Fixes

  • New raise_for_status_with_body reads the body on 4xx/5xx and includes it in the error message, preferring error/message/detail JSON fields.
  • Structured error fields are shown as raw JSON instead of falling back to a generic string; body reads are capped at 64 KiB and fall back to UTF-8 when the charset is missing or unknown.
  • Used for tool calls and discovery in HTTP, SSE, and Streamable HTTP protocols; existing ClientResponseError handlers still work.