Learning path · 5 steps
Handle HTTP errors and ambiguous writes in a small client
Start with the supplied support-service client and finish with a reviewed patch, regression tests and a short explanation of its behavior. The same two files carry the work from the first question to the final check: one mistakes an HTTP error for ticket data, while the other repeats a write after an ambiguous failure.
In this guide 6 sections
These walkthroughs use the downloadable synthetic support-service project. Work in a disposable copy so you can compare the proposed changes with the original defects. Each tool needs separate authorized access; the starter includes no production credentials or incident data.
What you will build
A checked support-service client
You will produce two corrected modules, focused regression tests, and a change note a reviewer can use. No web server, real tickets or package installation is needed for the JavaScript project. Install and authorize one of the linked assistants separately.
Included example files
A small support-service project
Synthetic code, logs, a deliberately stale runbook, and six support tickets. The JavaScript uses Node.js 22+ with no packages or network calls. Product accounts and model access are separate.
- client.mjs
- retry.mjs
- client.test.mjs
- retry.test.mjs
- checks/
Get a known starting point
Unpack the starter into a disposable folder and install one assistant you are authorized to use. Read the README and run the happy-path tests. Run each contract check separately to see the supplied defects before asking for a fix. These failures are expected in the teaching project.
Terminal commandnode --test client.test.mjs retry.test.mjsCheck before continuingBoth baseline tests pass. The 503 contract and ambiguous-write contract fail for reasons you can explain.
Map the two failure paths
Ask your chosen assistant to connect each contract to its implementation, without editing. This produces a plan for one small client rather than an open-ended repository cleanup. Keep permission settings consistent with exploration.
Request to adaptRead client.mjs, retry.mjs and checks/. Explain how the two failing contracts reach the current return values. For each, name the smallest behavior change and the regression test that would prove it. Do not edit or rewrite the supplied contract checks.Check before continuingThe plan identifies unchecked HTTP status and an unsafe second send, not unrelated refactors.
Fix the HTTP error path
Approve a focused change to client.mjs and a regression test. Follow the Claude Code walkthrough for a worked example of placing the status check before JSON parsing; the same contract can be discussed with your selected assistant.
Terminal commandnode --test client.test.mjs checks/client-contract.test.mjsCheck before continuingThe happy path still returns T-101; a 503 now rejects with HTTP 503 before its body is read.
Stop the duplicate write
Work through retry.mjs next. The transport can create a ticket and lose its response, so repeating the send is not justified. Preserve the public function name and rejection rather than inventing an idempotency service this project does not have.
Request to adaptFix retry.mjs to meet the single-send contract. Add a regression test that checks the side effect count and original rejection. Keep the successful-call behavior and supplied contract unchanged. Explain the trade-off in recovery behavior.Terminal commandnode --test retry.test.mjs checks/retry-contract.test.mjsCheck before continuingOne write is attempted and the original response-lost error reaches the caller.
Leave a reviewable result
Read the entire diff and run the combined command below. Write a short CHANGELOG.md explaining both defects, the checked behaviors and the remaining limits. You can ask Pi or the same assistant to review that note against the files, but the final explanation should survive your own inspection.
Terminal commandnode --test client.test.mjs retry.test.mjs checks/client-contract.test.mjs checks/retry-contract.test.mjsCheck before continuingFour supplied checks pass, no contract was weakened, and the change note explains both guarantees.
Check the finished project
node --test client.test.mjs retry.test.mjs checks/client-contract.test.mjs checks/retry-contract.test.mjsAll four supplied checks should pass only after both defects are fixed. Keep the contract checks unchanged. In your change note, explain why a failed HTTP response is rejected before body parsing, and why this write operation has no automatic retry. Add coverage for your real application before adopting the pattern.
Tool guides for this path
An authored walkthrough using the synthetic starter project and linked official tool documentation. Baseline fixture behavior and the local evaluator were checked. The assistants, review service and model calls were not run for this path.
Browse all learning paths