API返回200却JSON解析失败：HTML错误页、空响应与Content-Type排查
直接答案
请求状态为200但response.json或JSON.parse报错时，按响应头、原始正文、重定向、网关错误、空响应和JSON语法逐层定位。
症状、差异与判断依据
直接答案
先不要直接解析JSON。检查最终响应URL和重定向历史，再读取 Content-Type、Content-Encoding 与正文长度；把正文作为文本保存前几百个字符并脱敏。如果Content-Type不是JSON、正文以HTML标签开头或为空，应修复网关、认证或服务端响应；如果确实是JSON，再根据解析错误的行列号检查截断、尾逗号、单引号、非法控制字符、BOM或错误编码。
一、为什么200不等于JSON有效
HTTP状态码和媒体类型解决不同问题。200描述请求结果，Content-Type描述响应正文的媒体类型。合法的200响应可以是HTML、文本、图片或JSON。客户端若不检查媒体类型，直接按JSON解析任何200正文，就会把协议问题伪装成JSON语法问题。 有些网关会错误地把上游错误包装成200；单页应用服务器也可能对不存在的API路径返回前端 index.html。因此要同时查看状态、最终URL、Content-Type和正文，而不是只看状态码。
二、先记录完整响应元数据
排查记录至少包含：请求方法、脱敏URL、状态码、最终URL、重定向链、Content-Type、Content-Length、Content-Encoding、请求ID、正文实际字节数和前几百个字符。不要把令牌、Cookie、个人信息或完整业务数据写进普通日志。 如果响应很大，只保存哈希、长度和有限预览。二进制或压缩数据不要直接按终端文本打印，先确认Content-Encoding以及客户端是否已经自动解压。
三、最常见原因
收到HTML而不是JSON：正文以 <!doctype html、<html 或登录页面标题开头，通常说明请求进入了错误路由、认证跳转、反向代理错误页、CDN/WAF页面或前端应用回退页。 重点检查：API基础URL是否正确；路径是否少了版本前缀；Authorization是否失效；客户端是否自动跟随302到登录页；Host和TLS SNI是否正确；代理是否把 /api/ 重写到静态站；WAF是否只对特定User-Agent或地区返回挑战页。 修复应发生在路由或服务端，不能通过删除HTML标签再尝试解析来掩盖问题。
四、Content-Type应该怎样判断
常见JSON响应类型是 application/json，也可能使用以 +json 结尾的供应商媒体类型。检查时应解析媒体类型，而不是要求整个字符串严格等于 application/json，因为它可能包含 charset 参数。 浏览器Fetch示例可先验证响应： 读取为text后不能再对同一Response调用 response.json()，因为响应流通常只能消费一次。诊断代码应在受控范围内记录预览，而非完整敏感正文。
五、空响应和204
空字符串不是有效JSON。接口若没有正文，应返回204 No Content，客户端也应按状态和Content-Length跳过解析。若接口契约要求JSON，则服务端应返回有效对象、数组或 null，并使用正确Content-Type。 Python Requests官方文档说明，204或无效JSON调用 r.json() 会抛出 requests.exceptions.JSONDecodeError。所以捕获异常后仍要检查状态、头和原始文本，不能把所有异常统一解释成网络失败。
六、正文被截断
错误信息包含“unexpected end”“unterminated string”或在文档末尾失败，可能是响应被截断。比较Content-Length与实际字节数，检查代理超时、连接中断、服务进程退出、压缩传输错误和客户端读取限制。 分块传输没有固定Content-Length时，要检查客户端或代理是否完整读到结束标记。重试可能偶尔成功，但仍应通过服务器和代理日志定位截断位置。
排障步骤与验证
七、JSON语法本身无效
JSON不允许尾逗号，属性名和字符串必须使用双引号，不能直接包含未转义控制字符。JavaScript对象字面量能运行，不代表它是合法JSON。Python JSONDecodeError 提供 pos、lineno 和 colno，可用于定位失败位置。 常见错误包括： {"a":1,} 尾逗号。 {'a':1} 使用单引号。 日志或模板在JSON前后追加文本。 多个JSON对象直接拼接，没有数组或分隔协议。 字符串中出现未转义换行。 代理把错误提示插入响应中间。 不要用正则“修复”任意JSON后继续处理关键数据，应修复产生无效JSON的源头。
八、编码、BOM与压缩
JSON交换通常使用UTF-8。错误charset、重复解码、UTF-8 BOM或把压缩字节当成文本，都可能导致解析失败。先看Content-Encoding，确认HTTP库是否自动解压；再检查解码后的首字符是否有不可见BOM。 不要在不知道源编码时用 errors="ignore"，它可能静默删除字符并改变数据。保存原始字节哈希和响应头，按接口契约解码。
九、重定向与认证陷阱
许多HTTP库默认跟随重定向。原始API可能返回302，最终登录页返回200，调用者最后只看到“200 + HTML”。记录history和最终URL能立即暴露这一问题。 API认证失败更适合返回明确的401或403 JSON错误，而不是跳到交互式登录页。浏览器页面和机器API应使用不同的错误处理策略。
十、客户端安全解析模式
稳健客户端应按顺序：检查传输异常；记录状态与请求ID；检查允许的状态码；处理204和空正文；验证媒体类型；限制最大正文；最后解析JSON并将语法错误与HTTP错误分类。 错误报告可以包含解析行列号、媒体类型、字节数和脱敏预览，但不要把完整响应、认证头或用户数据暴露给普通用户。
十一、服务端修复清单
API所有成功响应输出有效JSON和正确Content-Type。 错误使用合适的4xx或5xx，而不是统一200。 认证失败返回机器可读错误，不跳HTML登录页。 反向代理仅把前端路由回退到index.html，不覆盖API路径。 空成功响应使用204，或按契约返回有效JSON。 设置请求ID并贯穿网关、服务和客户端日志。 对截断、压缩、超时和大响应建立集成测试。
十二、常见错误
只判断200就调用JSON解析。 把所有JSONDecodeError归类为网络故障。 在日志里输出完整令牌和响应正文。 忽略重定向后的最终URL。 用字符串替换尾逗号“修好”未知数据。 对204和空正文强制解析。 只在本机直连测试，不经过生产网关和CDN。
十四、总结
“200但JSON解析失败”不是单一错误。用状态码、最终URL、Content-Type、正文长度和脱敏预览先判断收到的究竟是什么，再区分HTML回退、空响应、截断、编码和语法问题。客户端要分类报告，服务端要用正确状态与媒体类型兑现接口契约。
常见问题
Content-Type是application/json就一定有效吗？
不一定。响应头可能配置错误，正文仍可能为空、被截断或语法无效。它是必要诊断信号，不是解析成功保证。
为什么浏览器看到200，代码却提示Unexpected token `<`？
通常因为正文开头是HTML，`<`来自doctype或标签。检查最终URL、认证跳转、代理错误页和API路由。
可以先调用response.json，失败后再读取text吗？
Fetch响应流通常只能消费一次。调试时先读取text，再显式JSON.parse，或在支持的环境使用clone。
重试能解决解析错误吗？
只有截断或临时网关故障可能偶发恢复。固定HTML、空正文或无效JSON重复请求仍会失败，应修复契约或路由。