Improve typed httpx error mapping and adapter guidance#820
Improve typed httpx error mapping and adapter guidance#820
Conversation
Handle typed httpx request and transport exceptions so timeout/protocol/redirect failures map to deterministic upstream errors instead of falling through as unhandled runtime failures. Add focused adapter coverage tests and a new Claude skill that documents how to build error adapters from existing project patterns. Made-with: Cursor
Codecov Report✅ All modified and coverable lines are covered by tests.
🚀 New features to boost your workflow:
|
Remove monorepo-specific file references from the build-error-adapter skill, add the official Arcade error-adapter documentation link, and fold in guidance from the public docs for explicit adapter usage and error-type selection. Made-with: Cursor
Extend the requests handler to map timeout, transport, protocol, redirect, and generic request exceptions into deterministic UpstreamError classifications with retry semantics, mirroring the typed httpx coverage. Add real requests exception tests to verify status, retryability, kind, and metadata mapping. Made-with: Cursor
Replace raw HTTP exception text in status-based adapter paths with safe generic user messages and move technical exception detail to developer_message. Update HTTP adapter tests to validate the new privacy split explicitly. Made-with: Cursor
Limit agent-facing fallback messages to safe, typed summaries for Google, Microsoft, Slack, and GraphQL adapters while preserving raw exception details in developer_message. Made-with: Cursor
Clarify how to avoid leaking sensitive vendor error details when exception content is uncertain by defaulting to safe agent-facing templates and reserving raw diagnostics for developer_message. Made-with: Cursor
|
@jottakka Could you make this easier to review by providing two side-by-side sets of examples in the PR summary by running an experiment: first, a list of real upstream errors as they appear before these changes, and second, the same errors as they appear after these changes? I'm having difficulty understanding what parts of errors are no longer in the message |
Increase the initial stdio initialize-response timeout for integration tests to absorb cold uv environment setup on fresh CI runners and prevent intermittent macOS 3.12 timeouts. Made-with: Cursor
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 2e445f9. Configure here.
| **mapper._build_extra_metadata(request_url, request_method), | ||
| "error_type": type(exc).__name__, | ||
| }, | ||
| ) |
There was a problem hiding this comment.
Identical helper method duplicated across two handler classes
Low Severity
_build_upstream_error is copy-pasted identically between _HTTPXExceptionHandler and _RequestsExceptionHandler. Both have the same signature, same body, and same construction of the UpstreamError. This duplicated logic increases the risk of the two drifting apart if the error construction logic changes later. It could be extracted into a standalone function or placed on BaseHTTPErrorMapper.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 2e445f9. Configure here.
2 participants
Summary
HTTPErrorAdapterto handle typedhttpxrequest/transport exceptions (timeouts, protocol errors, decoding failures, redirect-limit failures) with deterministicUpstreamErrormapping instead of falling through to unhandled runtime failures.libs/tests/sdk/test_httpx_adapter.pywith typedhttpxexception coverage andErrorKindassertions to lock retryability/classification behavior..claudeskill for building error adapters from project patterns and bumparcade-tdkversion to3.6.2.Test plan
uv run pytest libs/tests/sdk/test_httpx_adapter.py -quv run pytest libs/tests/sdk/test_graphql_adapter.py libs/tests/sdk/test_graphql_tooling.py libs/tests/sdk/test_google_adapter.py libs/tests/sdk/test_microsoft_adapter.py libs/tests/sdk/test_slack_adapter.py -qmake check(ruff/pre-commit pass; mypy reports pre-existing unrelated issues inlibs/arcade-cli/arcade_cli/authn.py,libs/arcade-cli/arcade_cli/main.py, andlibs/arcade-mcp-server/arcade_mcp_server/convert.py)Made with Cursor
Note
Medium Risk
Changes how
HTTPErrorAdapterand several provider adapters map exceptions toUpstreamError/UpstreamRateLimitError, which can affect retry behavior and surfaced error messaging. Risk is moderated by broad test updates covering new typed exception paths and message/developer_message splits.Overview
Improves upstream error adaptation to be more deterministic and privacy-safe across providers.
HTTPErrorAdapternow maps typedhttpxandrequestsexceptions (timeouts, transport/protocol/decoding errors, redirect limits, invalid URL/protocol) into consistentUpstreamErrorstatuses/kinds, and HTTP status errors now emit a safe agent-facing message with the raw exception moved todeveloper_message.GraphQL, Google, Microsoft Graph, and Slack adapters update their unhandled/fallback paths to avoid leaking
str(exc)inmessage, instead using an “unhandled ” template and storing details indeveloper_message. Tests are expanded/updated accordingly, the stdio E2E test increases the initialize read timeout for CI, a new.claudeskill doc is added for building adapters, andarcade-tdkis bumped to3.6.2.Reviewed by Cursor Bugbot for commit 2e445f9. Bugbot is set up for automated code reviews on this repo. Configure here.