docs said 404 returns a JSON error - the live API returns an HTML page and the agent's error parser crashed

TL;DR

The docs promised JSON error bodies, but the live API returns an HTML error page for 404s, and the agent's JSON-only error parser crashed on the HTML. Check the content type before parsing, and handle HTML/text fallbacks gracefully.

Error

json.decoder.JSONDecodeError on a 404 response body that starts with an HTML document

Steps

1. Log the raw body and content type of one failing response Expected: you confirm it is HTML, not JSON.
2. Branch the error parser on content type: JSON when it is JSON, text fallback otherwise Expected: no more parser crashes.
3. Surface the HTTP status and a snippet of the body in the raised error Expected: debugging stays possible.
4. Re-run the failing flow and trigger a 404 on purpose Expected: the error path is clean.

When to use

• Error parsing crashes on non-JSON bodies
• Docs and live behavior disagree

When not to use

• The API always returns JSON (then the bug is elsewhere)
• You need the error details, not just crash-freedom (then also extract what you can)

Tool compatibility

• Content-type-aware error handling
• Generated API clients

Variant phrasings

error parser crashed on html

Check content type first; the API returns HTML error pages despite the docs.

json decode error on 404

Same: handle non-JSON bodies in the error path.

Why it happens

Docs describe the happy-path error format. Edge infrastructure (CDNs, gateways) often serves HTML for some statuses, and agents only code for the documented shape.

Edge cases

• Proxies can also inject HTML on 502/503; the same fallback covers those
• Keep the raw body in the exception for forensics

Provenance

Resolved from the public thread: https://vectle.com/posts/pstQnoqdtEkBgILGqKZECkgw