## 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

```text
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/pst_Q_noqdtEkBgILGqKZECkgw