feature/Refused-start-raises-bare · L-260927-424b11

[lchoquel]

Every route of PipelexAPIClient now raises a typed ApiResponseError that is mthds's own error narrowed to ValidationErrorItem, so start_and_wait() or execute() on a method the plane refuses raises an error whose message and fields carry the reason, the failing pipe and the next step, instead of httpx's bare status line. The client overrides the new _raise_api_response_error seam of mthds, reads the shared members through ProblemDocument, and moves the gateway-timeout translation of execute and the bare-runner 404 translation of start onto the typed error, both of which the override would otherwise have silently disabled. The branch builds on mthds pinned at its dev commit and collapses onto the published 0.17.0 before it merges.

Closes L-260927-424b11

🤖 Generated with Claude Code

---

Summary by cubic

Every route of PipelexAPIClient now raises a typed ApiResponseError — mthds's own error narrowed to ValidationErrorItem — so a refused run reports the reason, the failing pipe, and the advised next step instead of httpx's bare status line.

Migration

• Callers that caught httpx.HTTPStatusError must catch ApiResponseError and read exc.status, exc.headers, and exc.request_url where they previously read exc.response.status_code, exc.response.headers, and exc.request.url.
• execute's gateway-timeout translation and start's bare-runner 404 translation now read the typed error; on start, a runner 404 that carries error_type but no code is read as a refusal, and only a 404 with neither is treated as a missing run store.

Dependencies

• mthds is upgraded to the published 0.17.0.
• Tests replay the dev plane's three real refusal bodies byte for byte from mthds-python, and the deferred version-handshake finding is recorded in wip/pr-50-review-notes.md.

^{Written for commit af35911. Summary will update on new commits.}

[lchoquel]

Review round 1 — profile 3, bar open, at 88805ea. Reviewers: cubic, Codex (review mode), code-review (level low); one verifier.

Fixed in 9d397e3:

• A 404 on start carrying the runner's error_type and no platform code (a method_ref with no package, relayed unchanged by the hosted API) was read as a missing run store, so start raised RunLifecycleUnavailableError and start_and_wait demoted the client to blocking execute for good. A missing route is now a 404 whose body carries neither code nor error_type. The logic predates this branch.
• The error_models module docstring still said ApiResponseError types its user_action with the lenient model declared there; it now names both UserAction types.

Deferred with a trace: the message's reason order is a copy of a private helper in mthds (L-260927-9d2df3, mthds-python); the JS twin's isMissingRoute404 has the same 404 bug (L-260927-578c32, pipelex-sdk-js).

Rejected: the mthds git-source pin (the sprint pin, collapsed onto the published 0.17.0 before merge), and a lost X-Request-ID fallback (ProblemDocument.make_from_response reads the header, and a test covers it).

Verdict: round 2 — bar defects — profile 3.

[lchoquel]

Review round 2 — profile 3, bar defects, at 9d397e3. Reviewers: cubic, Codex (review mode), code-review (level low). No verifier was needed.

Nothing fixed: no finding the bar admits.

Deferred with a trace: a 200 from /v1/version whose body is not JSON escapes the handshake. It predates this branch and makes no practical difference, since start fails the same way one request later (wip/pr-50-review-notes.md, unverified). The copied message-reason helpers stay deferred (L-260927-9d2df3, unverified).

The mthds git-source pin was raised again; it collapses onto the published 0.17.0 next, before the merge.

Verdict: converged. Round 2 at profile 3 was clean with full coverage, so nothing further is warranted.