[BUG] API Error: 400 The request body is not valid JSON

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

I often get this bug: API Error: 400 The request body is not valid JSON.

it should get a defensive errors='replace' in the serialization path.

EXAMPLE:
UTF-8 Surrogate Error — What It Is

Cause: The API received a string containing a lone Unicode surrogate character (U+D800–U+DFFF). These are valid in UTF-16 (used internally by JS/Python on some platforms) but illegal in UTF-8/JSON. The serializer chokes before it even writes a byte — hence line 1 column 1 (char 0).

Common Triggers in Your Workflow

┌──────────────────────────────────┬────────────────────────────────────────────────────────────────────────┐
│ Source │ Why it happens │
├──────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ Bash output with binary/mojibake │ A command returns bytes that Python decoded as lone surrogates │
├──────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ BigQuery results │ Rare but possible with malformed string columns │
├──────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ File reads on non-UTF-8 files │ Reading a Latin-1 or binary file that has bytes in the surrogate range │
├──────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ MCP tool responses │ An MCP server returning invalid UTF-8 in its JSON payload │
├──────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ Copy-paste from Windows/PDF │ UTF-16 surrogates that didn't survive re-encoding │
└──────────────────────────────────┴────────────────────────────────────────────────────────────────────────┘

What You Can Do

For Bash commands producing suspicious output, pipe through:
some_command | iconv -f utf-8 -t utf-8 -c # strips invalid bytes

For Python scripts, sanitize before returning results:
s.encode('utf-8', errors='surrogatepass').decode('utf-8', errors='replace')

To find the culprit fast — the error always happens right before an API call, so look at the last tool result in the session (Bash output, file read, or MCP response) for the offending content.

What Should Happen?

it should get a defensive errors='replace' in the serialization path.

Error Messages/Logs

API Error: 400 The request body is not valid JSON: str is not valid UTF-8: surrogates not allowed: line 1

Steps to Reproduce

not sure

Claude Model

Not sure / Multiple models

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.193 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_