Bug reporting for backend developers — the 2026 playbook
Reproduce client-reported API failures from the exact request the browser sent: 4xx vs 5xx triage, CORS preflight redirects, one-shot Fetch streams, HAR auth headers, and MCP
Why Backend Developers need a different playbook
Backend developers rarely see the bug. You see the aftermath: a ticket that says "the API failed," a 4xx or 5xx status, and a client who swears it worked yesterday. RFC 9110 says a 4xx means the client seems to have erred and a 5xx means the server is aware it erred, but the status code never tells you the exact method, path, query string, headers, and request body the browser actually sent. That gap is where most "cannot reproduce" tickets live. The bug you can replay is the bug you can fix.
This is the 2026 playbook for reproducing client-reported API failures from the request and response the browser really sent, not the one you assume it sent. It covers triaging 4xx versus 5xx from a captured payload, why a CORS preflight redirect never reaches your access log, why your own error logger keeps recording an empty response body off a one-shot Fetch stream, and how an AI agent can read the captured call over the Model Context Protocol and draft a failing test before you have finished reading the ticket.
Common pitfalls
The recurring mistakes that get bug reports bounced back — and how to avoid them.
Real-world examples
What these bugs look like in practice, and how to file them cleanly.
Client sends a different payload than the contract says
What it looks like: The endpoint returns 422 or 400 for one client but never in your tests. The frontend serializes a date, an enum, or a null in a shape your validator rejects, and the server log records only the status, not the offending body.
How to file it: Read the captured request body and replay it as curl. The diff between the assumed payload and the real one is usually the whole bug. Fix the serializer or widen the validator, then add the captured body as a regression fixture so it cannot silently return.
# Replay the EXACT failing request the browser sent
curl -i -X POST https://api.example.com/v1/orders \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token-from-capture>' \
--data-raw '{"items":[{"sku":"A1","qty":"2"}],"placedAt":"2026-06-03T00:00:00Z"}'
# qty is a string, not a number -> server returns 422Intermittent 500 that no local request reproduces
What it looks like: A 5xx fires for some users and never on your machine. The trigger lives in a specific header, query param, or oversized field the happy-path test never sends, so the unhandled exception stays invisible until a real user hits it.
How to file it: Per RFC 9110 a 5xx means the server knows it erred, so correlate the captured request id and timestamp with your server logs and traces, reproduce with the captured inputs, and convert that into a failing test before you touch the handler.
// Vitest/Jest repro built from the captured request
it('returns 200 for the payload that 500'd in prod', async () => {
const res = await app.inject({
method: 'POST',
url: '/v1/orders',
headers: capturedHeaders, // pulled verbatim from the capture
payload: capturedBody,
});
expect(res.statusCode).toBe(200);
});Response body is empty in logs but the request clearly failed
What it looks like: Your monitoring shows the failed status but a blank body, so you cannot see the error envelope the API returned. An interceptor consumed the Fetch stream before your logger read it, and the stream cannot be read twice.
How to file it: In code, clone the response before the first read so both the app and the logger get the body. For the bug already in front of you, the client-side network capture preserved the raw response body regardless of what your app did with the stream.
// Fetch body is a one-shot stream — clone before reading twice
const res = await fetch(url, init);
const forLog = res.clone();
const data = await res.json(); // app consumes the stream
const raw = await forLog.text(); // logger still sees the bodyWorkflow comparison
The same bug, filed two ways — with and without a capture tool.
| Feature | BugMojo | Hand-collected HAR / DevTools |
|---|---|---|
| Capture the exact failing request + response body | One-click, raw body preserved | Manual Export HAR / Copy as fetch |
| Keep Cookie / Authorization for a 401/403 replay | Retained for replay | Sanitized HAR strips them |
| AI agent reads the request via MCP (Claude Code, Cursor) | Yes — agent drafts a failing test / curl | No — HAR/screenshot a human must re-key |
| Pair the network call with DOM replay + console | Captured together in one report | Separate tabs, manually correlated |
| Server-side traces, exception aggregation, error rates | Not its job — pair with APM/Sentry | DevTools has none either |
| Distributed tracing across services | No — use OpenTelemetry/Datadog | No |
| Zero-setup Quick Capture | No project, no SDK | Account / SDK required |
BugMojo records the DOM, console, and network — then ships a one-click ticket with the full replay attached. No SDK, no setup.
Try BugMojo freeFrequently asked questions
Frequently asked questions
Sources
- RFC 9110: HTTP Semantics — §15.5 (4xx, "client seems to have erred") and §15.6 (5xx, "server is aware that it has erred") — IETF / RFC Editor (2022-06)
- Using the Fetch API — response/request bodies are ReadableStreams; cannot read the same body twice; use Response.clone() — MDN Web Docs (2025)
- CORS errors — application/json is not safelisted so it triggers an OPTIONS preflight; preflight redirects are not allowed — MDN Web Docs (2025)
- Network features reference — Export HAR (sanitized) excludes Cookie, Set-Cookie, and Authorization headers; Copy as fetch / Copy as cURL — Chrome for Developers (2024-07-16)
- 2024 State of the API Report — only 37% prioritize API testing; 1% do not test APIs; 5% of teams see API-change failure rates above 25% — Postman (2024-10)
- 2025 Developer Survey — 45.2% say debugging AI-generated code is more time-consuming; 66% cite AI "almost right, but not quite" as top frustration — Stack Overflow (2025-12)
- Specification 2025-11-25 — Model Context Protocol (open protocol connecting LLM apps to external data/tools via JSON-RPC 2.0) — Model Context Protocol (2025-11-25)