ClientPayloadError是aiohttp在解析响应体时因服务端违反HTTP规范（如Content-Length不匹配或chunked编码错误）而抛出的异常；它常出现在POST/PUT请求中，根本原因是服务端实现不合规，而非客户端代码错误。
ClientPayloadError 是什么，为什么它总在 POST/PUT 时冒出来
ClientPayloadError 不是网络超时或 DNS 失败那种“连不上”的错，而是 aiohttp 在解析响应体时发现服务端返回了不合规的 Content-Length 或分块编码（chunked）格式——比如声称发 1024 字节却只发了 800 字节，或者 chunk 头写错了。它常出现在你用 session.post() 提交表单、上传文件、调用某些老旧或自定义后端 API 的时候。
根本原因不是你的代码写错了，而是服务端 HTTP 实现没严格遵循 RFC 7230。但你得绕过去，因为没法立刻让对方改服务器。
加 timeout + raise_for_status() 之前先 catch 它
很多人习惯链式调用：await resp.json()，结果一出错就直接崩，根本没机会 inspect 响应头。必须把异常捕获提前到读 body 之前：
try:
async with session.post(url, json=payload) as resp:
resp.raise_for_status() # 这里可能触发 ClientPayloadError
data = await resp.json()
except aiohttp.ClientPayloadError as e:
print(f"Payload error: {e}")
# 此时 resp 可能已部分读取，但不能继续 await resp.json()
except aiohttp.ClientResponseError as e:
print(f"HTTP {e.status}: {e.message}")
- 不要在
raise_for_status()后再做await resp.text()—— 如果 payload 已损坏，第二次读会再抛一次ClientPayloadError -
resp.content是个StreamReader，如果想看原始字节，得用await resp.content.read()，但注意：一旦读过，后续resp.json()就失效 - 如果服务端偶尔出错但业务可容忍，可以跳过
raise_for_status()，直接尝试读 body 并处理空/乱码
用 auto_decompress=False 绕过 gzip 解压失败
某些代理或旧版 Nginx 会在启用 gzip 时错误截断压缩流，导致 aiohttp 解压时校验失败，最终包装成 ClientPayloadError。这不是内容长度错，而是 zlib 流不完整。
立即学习“Python免费学习笔记（深入）”；
临时方案是在 aiohttp.ClientSession 初始化时关掉自动解压：
async with aiohttp.ClientSession(auto_decompress=False) as session:
async with session.post(url, json=payload) as resp:
body = await resp.read() # 得自己判断是否 gzip，再手动解压
- 关掉后，
resp.headers.get("Content-Encoding")若为gzip，你就得用zlib.decompress(body, wbits=16+zlib.MAX_WBITS) - 别忘了检查
resp.status，因为auto_decompress=False也会让 4xx/5xx 响应体不被自动拦截 - 这个选项影响所有请求，不适合混合使用 gzip/non-gzip 的服务端
换用 TCPConnector 的 force_close 和 keepalive_timeout
连接复用（keep-alive）有时会让损坏的响应污染后续请求的 socket 缓冲区，尤其当服务端提前关闭连接却不发完 chunk trailer 时。aiohttp 默认复用连接，容易把上一个请求的残缺 payload 误认为下一个的开头。
对问题接口单独配置连接器：
connector = aiohttp.TCPConnector(
force_close=True, # 每次请求后立即 close socket
keepalive_timeout=0, # 禁用 keep-alive
enable_cleanup_closed=True
)
async with aiohttp.ClientSession(connector=connector) as session:
...
-
force_close=True最有效，但代价是每次请求都重连，QPS 下降明显 - 如果只是偶发，优先试
keepalive_timeout=0，它允许复用但不保持长连接 - 别全局设这个 connector，只给明确出问题的
session实例用
真正麻烦的是那些既不规范又不暴露 debug header 的内部服务——你得靠 resp.headers 和 await resp.content.readany() 一点点试探边界。payload 错误本身不报具体哪一行，只能靠排除法定位是长度标错、chunk 格式错，还是中间件偷偷改了 body。
