diff --git a/CHANGELOG.md b/CHANGELOG.md
index c13c3b5..fa62e7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,33 @@
 # Changelog
 
-## 未发布
+## 1.2.0(2026-08-16)
 
-- 打包元数据补齐: `readme` 与 `[project.urls]`。1.1.2 及之前的包在 registry 页面上**没有任何说明正文**(缺 `readme` 时 twine 只警告不阻塞),也没有仓库链接。代码零变更,随下一个版本生效。
+网关拒绝一次调用时,**它说的话不再丢失**(issue #10)。下游一轮 1050 张医学影像的批处理里,1 张在读表格这一步收到 400、被判确定性失败而放弃;事后想知道"这张图到底哪里不合规",无从查起——响应体在 transport 翻译层之后就不存在于进程任何位置了。
+
+根因是三条留存通道同时为空: `_status_to_error` 手上握着 `body_text` 却只用于 429 的类型细分,该模块没有任何 logger 调用,异常类也没有承载响应体的字段。而库的逐次遥测写的是 `str(exc)`,即 message——所以**只给异常加字段并不能让它进遥测表**,必须两者都做。
+
+### 新增
+
+- **四分类错误新增 `body_text` 字段**(加在 `PolyGatewayError` 基类): 非 2xx 响应体的摘要。与 `ResultInvalidError.raw_text` 分工明确——前者是"对方拒绝的理由"(非 2xx),后者是"2xx 但内容不可解析时的模型输出"。scope 级错误(`GatewayUnavailableError` 一族)恒为空串: 它们没有单一响应体可言。
+- **同一份摘要同时进入异常 message**,故 SQLite/Postgres 遥测的 `error` 列里直接可查,下游不必为此单独埋点。
+
+### 行为变更
+
+- **非 2xx 的 message 末尾追加 ` | {响应体摘要}`**,覆盖两个 transport 的**全部**分支: chat 的 400 / 401·403 / 4xx 兜底 / 5xx / 429 两支(含 `insufficient_quota`),以及 OCR 的全部分支。issue 只报告了 chat 的 400,但 401 会 `force_open` 整个源、OCR 侧 message 原本只有一个状态码,是同一个缺陷的其余分支。
+- 摘要口径: 先折叠空白(错误体常是缩进 JSON,原样拼进 message 会把一行日志炸成多行),再限长 **2048 字符**(对齐 Kubernetes client-go 同场景的 `maxUnstructuredResponseTextBytes`)。超长时**保留头 1400 + 尾 600**并记下省略字数——JSON 错误体的 `code` / `request_id` 收在尾部,头部硬切正好会切掉向网关方追查时唯一有用的那部分。
+- 遥测 `error` 列因此变长: 纯 ASCII 约 2KB/条,最坏(5xx 重试 3 次)一次调用约 6KB。
+
+### 不变
+
+- **状态码 → 错误分类的映射逐条未动**(ARCHITECTURE §6.2 表),`retry_after_s` 解析、429 免重试预算、`insufficient_quota` 细分全部保持——429 的类型判定仍解析**未截断的原文**,若改用摘要,超长 body 的配额耗尽会退化成普通限速、该源不再 `force_open`。
+- 异常类型树、`str(exc)` 之外的字段、遥测 22 字段与列序、DDL 全部未变。**错误面零变更**,下游 `except` 写法不受影响。
+- 400 仍按确定性失败处理(不重试不换源)。**但请注意**: 经第三方中转部署时,中转自身抖动也会回 400,从状态码上与"你的输入有问题"分不开(下游实测: 同一份字节 sha256 一致、重发 15 次全部成功,失败那次 `prompt_tokens=0` 且耗时远低于任何成功调用)。库不改默认语义——直连供应商时重试只会白烧配额——但 `body_text` 现在给了下游自行区分的判据。
+
+### 升级提示
+
+README 的安装 pin 由 `==1.1.*` 改为 `>=1.2,<2`。**仍按 `==1.1.*` 安装的下游会静默停在 1.1.2**,拿不到本次修复且没有任何报错,请同步改自己的依赖约束。
+
+- 打包元数据补齐: `readme` 与 `[project.urls]`。1.1.2 及之前的包在 registry 页面上**没有任何说明正文**(缺 `readme` 时 twine 只警告不阻塞),也没有仓库链接。代码零变更,自本版生效。
 
 ## 1.1.2(2026-08-07)
 
diff --git a/README.md b/README.md
index 4fbf7ca..ebe35a2 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
 
 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]==1.1.*"
+    "polygateway[redis,postgres,structured]>=1.2,<2"
 ```
 
 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -125,6 +125,8 @@ except RequestRejectedError:
 
 预算耗尽/全源熔断时抛 `GatewayUnavailableError` 族(`CircuitOpenError` / `AllSourcesExhausted`),携带 `scope` / `reason` / `retry_after_s` / `per_source_reasons`,供任务队列做延期重投。
 
+**网关拒绝的理由不会丢失**(1.2.0 起):非 2xx 的响应体经折叠与截断后同时进入异常 message 与 `exc.body_text`,故遥测表的 `error` 列里就能看到网关的原话——不必再为查一次 400 单独埋点。截断保头保尾(总长 2048 字符),JSON 错误体尾部的 `code` / `request_id` 不会被切掉。**经中转部署时请注意**:第三方中转服务自身抖动也会回 400,从状态码上与"你的输入有问题"无法区分;库仍按确定性失败处理(直连供应商时重试只会白烧配额),批处理下游宜据 `body_text` 自备兜底分类。
+
 ### 哪些异常会到达调用方
 
 上表的"库内行为"一列描述的是**治理动作**,不是调用方要处理的东西。四类里有两类**根本到不了调用方**——它们被重试循环接住,预算耗尽时统一包成 `AllSourcesExhausted`。这个区分只看类型树和 docstring 是读不出来的,曾让下游据此写错整段设计文档,故在此列明:
diff --git a/pyproject.toml b/pyproject.toml
index 60581d3..ba6ca27 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polygateway"
-version = "1.1.2"
+version = "1.2.0"
 description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
 # registry 包页面的正文只认这一项:缺了页面就是一片空白(1.1.2 的教训,twine 会警告
 # long_description missing 但不阻塞上传)。README 在打包时被固化进产物,发布后再改无效。
diff --git a/research-wiki/ARCHITECTURE.md b/research-wiki/ARCHITECTURE.md
index 5168f23..d36896b 100644
--- a/research-wiki/ARCHITECTURE.md
+++ b/research-wiki/ARCHITECTURE.md
@@ -396,6 +396,10 @@ flowchart TB
 | **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应) |
 | 解析层失败(结构化输出/OCR ZIP) | `ResultInvalidError` |
 
+**响应体留存(2026-08-16,Gitea issue #10;设计 `designs/2026-08-16-issue10-error-body-retention-design.md`)**: 上表每一条 HTTP 翻译**都必须携带响应体摘要**——摘要同时进入异常 message 与 `PolyGatewayError.body_text`(1.2.0 新增基类字段)。两者都要,因为逐次遥测写的是 `str(exc)`,只加字段进不了遥测表,而"事后可查"正是这条要求的目的。摘要口径由 `transports/_http_errors.summarize_body` 单点实现(折叠空白 → 限长 2048 字符 → 超长保留头 1400 + 尾 600 并记省略字数),两个 transport 共用,**不得各写一份**——issue #10 的成因正是"只有 429 那一支用了响应体"。`body_text` 是旁路数据,不参与任何治理判定;`_translate_429` 的类型细分仍解析未截断原文(摘要会破坏 JSON,改用它会让超长 body 的 `insufficient_quota` 退化成普通限速)。
+
+**400 在中转拓扑下的语义提醒**(同上): 第三方 API 中转服务自身抖动时也会回 400,从状态码上与供应商的"输入非法"无法区分(下游实测: 同一份字节重发 15 次全成功,失败那次 `prompt_tokens=0`、耗时远低于任何成功调用,即请求在推理开始前被挡)。本表**不改** 400 → `RequestRejectedError` 的映射——直连供应商时重试只会白烧配额,且改默认语义等于让所有直连用户为一种部署形态买单;库改为把判据(`body_text`)交给下游自行区分。
+
 ### 6.3 "坏结果 ≠ 坏服务"(ResultInvalidError 语义,继承 CHSAnalyzer)
 
 由输入内容决定的**确定性失败**(这张图就是解析不出表格、这段输出就是修不成 JSON):服务是健康的,换源重试只会白烧配额。因此熔断器记成功、不换源、异常上抛消耗业务侧的失败预算。出处:`CHSAnalyzer governance.py:237-239`。
diff --git a/research-wiki/designs/2026-08-16-issue10-error-body-retention-design.md b/research-wiki/designs/2026-08-16-issue10-error-body-retention-design.md
new file mode 100644
index 0000000..5988545
--- /dev/null
+++ b/research-wiki/designs/2026-08-16-issue10-error-body-retention-design.md
@@ -0,0 +1,238 @@
+# HTTP 错误响应体留存设计(Issue #10)
+
+- **日期**: 2026-08-16
+- **来源**: Gitea Issue #10(下游 1050 张医学影像批处理,1 张收到 400 被判确定性失败;事后无从查证原因。基于 1.1.2 源码核查)
+- **状态**: **已批准(2026-08-16)**,待 `writing-plans`
+- **触发档位**: 强制(`errors.py` 属最内层内核,新增公共字段即变更库对下游的承诺)
+- **方案范围**: 人类明确要求单一方案(2026-08-16),故本文不列平行备选,仅在 §6 记录被否决路线及否决理由(体例沿用 Issue #7/#8 设计)
+
+## 1. 目标与非目标
+
+| | 内容 |
+|---|---|
+| **G1** | 网关拒绝一次调用时,**它说了什么必须可事后查证**——库自己的遥测表里就能查到,不依赖下游额外埋点 |
+| **G2** | 留存口径覆盖 transport 层**全部**非 2xx 分支与**全部** transport(chat / embedding / stream / OCR),杜绝"只修 400 → 下次 401 复发" |
+| **G3** | 摘要文本单点规范化(折叠空白 + 截断 + 截断标记),message 与结构化字段**取同一份串**,两处永不打架 |
+| **G4** | 不改变任何状态码 → 错误分类的映射(ARCHITECTURE §6.2 表原封不动),下游 `except` 写法零影响 |
+| **非目标** | 不改 400 的治理语义(不重试不换源,见 §5.2);不新增遥测列(见 §6.1);不新增配置项;不做错误分类可插拔(见 §6.4);不顺手修 `_status_to_error` 的 `operation` 硬编码缺陷(见 §5.4) |
+
+### 1.1 Issue 前提的两处修正(按 1.1.2 源码核实)
+
+| Issue 原文 | 实际情况 |
+|---|---|
+| 建议方向一「让异常带上截断后的响应体……就能让下游把它记进日志和遥测」 | **只做这一半解决不了 Issue 自己陈述的痛点**。库的逐次遥测写的是 `error=str(exc)`(`middleware/retry.py:558` → `middleware/telemetry.py:89` → `telemetry/sqlite.py:43` 的 `error TEXT` 列),即**异常 message**。新增字段不会进库的遥测表;下游说的"写进遥测表"是他们自己的埋点。故本设计**两件都做,且以 message 为主**(§3.3) |
+| 缺陷范围 = 400 分支 + 4xx 兜底 | 实为 **6 处同构**:`openai_compat._status_to_error` 的 400 / 4xx 兜底 / 401·403 / 5xx 四支,`_translate_429` 的两支(读了 body 判 `insufficient_quota`,但 message 仍不带),以及 `monkey_ocr._classify_status:74-88` 的**全部**分支(message 只有 `HTTP {status}`)。Issue 场景是"读表格",极可能正落在 OCR 路径 |
+
+## 2. 根因:诊断信息在翻译层被丢弃,而遥测只看 message
+
+`_status_to_error`(`transports/openai_compat.py:131-143`)手上握着 `body_text`,却只把它用于 429 的类型细分,翻出的异常与 message 都不携带它。响应体在这一层之后**不再存在于进程任何位置**:该模块无 logger(grep `logger|loguru` 零命中),异常类无字段,遥测只写 message。
+
+三条留存通道同时为空,是"永久查不到"的完整解释:
+
+| 通道 | 现状 | 本设计后 |
+|---|---|---|
+| 日志 | 模块无 logger | 仍无(§6.2:不加日志) |
+| 异常字段 | 无承载处 | `body_text`(§3.1) |
+| 库遥测 `error` 列 | 只有 `"{源名} 请求被拒: 400"` | message 携带摘要(§3.3) |
+
+## 3. 选定方案
+
+### 3.1 内核:`PolyGatewayError` 基类新增 `body_text`
+
+```python
+class PolyGatewayError(Exception):
+    def __init__(self, message, *, source_name=None, status_code=None,
+                 operation=None, body_text: str = "") -> None:
+```
+
+**加在基类而非 `RequestRejectedError`**:这些错误全部由同一个 HTTP 响应翻译而来,"对方说了什么"与"它属于哪一类"正交。只给一个子类加,下次给 `SourceDeadError` 加又是一次公共 API 变更 + 一次人类门。
+
+与既有 `ResultInvalidError.raw_text`(`errors.py:77`)的界限必须在 docstring 钉死,否则两个"原文字段"必然被混用:
+
+| 字段 | 语义 | 来源 |
+|---|---|---|
+| `body_text` | **非 2xx** 的 HTTP 错误响应体摘要——对方**拒绝**你的理由 | transport 翻译层 |
+| `raw_text` | **2xx** 但内容不可解析时的模型输出原文 | 结构化解析层 |
+
+`GatewayUnavailableError` 一族继承到一个恒空的 `body_text` 不是噪音:scope 级失败本就"没有单一响应体可言",空串是对这件事的如实表达。
+
+### 3.2 共享单元:`transports/_http_errors.py`(新建,~40 行)
+
+两个 transport 各有自己的状态码分类逻辑(OCR 无 429 细分,有意保留,见 `monkey_ocr.py:53-54`),但**摘要口径必须同一份**,否则就是下一个"只修一半"。两函数:
+
+| 函数 | 职责 | 关键防御 |
+|---|---|---|
+| `summarize_body(text) -> str` | 折叠空白 → 按 §3.4 的机械规则截断 | 空/空白入参返回 `""` |
+| `response_body(response) -> str` | 从 `httpx.Response` 取已缓冲文本 | `ResponseNotRead` → 返回 `""`,**绝不触发网络读** |
+
+- **折叠空白不是洁癖**:错误体常是缩进 JSON,直接拼进 message 会让一行日志炸成多行、遥测列不可读。
+- **截断必须留标记**:不标记,读的人分不清"网关只说了这么多"和"库切的"。
+- **`response_body` 的防御是硬要求**:`monkey_ocr._classify_status` 只拿得到 `httpx.HTTPStatusError`,若某天 OCR 走 stream 请求,`.text` 会抛 `ResponseNotRead`,把一次可分类的 4xx 变成泄漏的 httpx 异常——**违反"一切失败必须落入四分类"铁律**。诊断信息缺失绝不能升级为崩溃(降级方向,§4.2)。
+
+放在 `transports/` 私有模块而非 `errors.py`:职责是"HTTP 响应 → 领域错误"的工具,放内核会稀释 `errors.py` 的单一职责(P3)。两个 transport 同 import 一个私有模块,不构成 transport 之间的互相依赖,import-linter 的 layers 契约(同层 `|` 独立性)不受影响。
+
+### 3.3 翻译层:表驱动收口,message 与字段共用一份摘要
+
+`_status_to_error` 现在是五个分支各拼各的 message,新增摘要意味着五处重复。改为**分类表 + 单点拼装**,代码反而变短:
+
+```
+summary = summarize_body(body_text)          # 全函数只算一次
+ctx     = {..., "body_text": summary}        # 字段
+429 → _translate_429(source, body_text, headers, ctx)   # 需原文判 type,单列
+其余 → cls, label = _STATUS_MAP 查表 → cls(_compose(source, label, status, summary), **ctx)
+```
+
+message 形态:`"{源名} {标签}: {状态码} | {摘要}"`;**摘要为空时不拼后缀**,避免出现悬空的 ` | `。分隔符取 ` | ` 而非既有的 `: `,让"库的话"与"网关的话"一眼可分。
+
+**429 也拼,不设例外**:例外就是下一个复发点。`insufficient_quota` 那支尤其需要(配额细节全在 body 里);普通限速 body 通常很短。代价是高频限速场景遥测 `error` 列变长,由 `_ERROR_BODY_CAP` 兜住。
+
+`monkey_ocr._classify_status` 同款处理:`summary = summarize_body(response_body(exc.response))`,message 追加同一后缀,`ctx` 带上字段。
+
+### 3.4 常量取值
+
+**机械规则(实现与测试逐字照此)**:
+
+```
+_ERROR_BODY_CAP = 2048    # 字符(非字节),含省略标记在内的最终总长上限
+_HEAD_CHARS     = 1400
+_TAIL_CHARS     = 600
+
+折叠空白后 len ≤ 2048  →  原样返回
+否则                   →  s[:1400] + f"…(略 {len(s) - 2000} 字)…" + s[-600:]
+```
+
+> 规则必须写成算术而非叙述:"截断至 cap 并补标记"能同时被读成总长 2048 与 2049,两者会让测试断言与遥测长度承诺对不上(Codex 审查 2026-08-16 提出)。
+
+**头尾保留而非头部硬切**(2026-08-16 调研决策)。截断的对象是**结构化 JSON 错误体**,信息分布头重尾也重:人话(`message`)在前,机器可判的 `type` / `code` / `param` / `request_id` 在后。Issue 给出的真实样本即 `"code":"invalid_parameter_error"` 收尾——头部硬切正好切掉向网关方追查时唯一有用的那部分。省略标记记下**被省略的字符数**,读的人才知道自己丢了多少,不会误以为网关只说了这么多。
+
+按**字符**而非字节切:多字节字符不会被切成半个(Sentry 曾为按字节切开 issue #1691),且 `error TEXT` 列无定长约束,无需字节口径。
+
+### 3.4.1 取值依据:同场景开源实践
+
+| 项目 | 场景 | 上限 | 保留策略 |
+|---|---|---|---|
+| **Kubernetes client-go** `rest/request.go` | **读 HTTP 错误体生成错误信息**(与本设计同构) | `maxUnstructuredResponseTextBytes = 2048` | 头部硬切 |
+| OpenAI Python SDK `_exceptions.py` | 异常对象持有 body | **不截断**(内存对象,不落库) | — |
+| Sentry Python `strip_string` | 事件写入前 trim | `max_value_length`,2.34.0 前默认 1024 | 头部 + `...`,另用 metadata 记原长 |
+| Elastic APM | 长字段 | keyword 1024 / long field 10000 | 截断带省略号 |
+| Python 标准库 `reprlib` | 给人读的长字符串 | `maxstring` | **头 + 尾,中间省略** |
+
+**2048 对齐 k8s client-go**——它是唯一与本设计同场景(读 HTTP 错误体做诊断)的成熟先例。初稿的 500 仅以 issue 的单个样本(约 160 字符)为据,是拿一个样本定上限,已废弃。头部硬切在 k8s/Sentry 成立是因为它们截的是任意文本;本设计截的是结构化 JSON,故取 `reprlib` 的头尾策略。
+
+遥测代价:纯 ASCII 约 2KB/条,纯中文最多约 6KB/条;5xx 重试 3 次即一次调用最多约 18KB。批处理场景(1050 次调用、5% 失败)约 300KB,`TEXT` 列可忽略。
+
+message 与 `body_text` **共用同一变量**,不设两个长度:两份不同长度会让"遥测里看到的"与"下游 catch 到的"对不上,排查时反而多一层困惑。
+
+### 3.5 改动清单
+
+| 文件 | 改动 |
+|---|---|
+| `errors.py` | 基类新增 `body_text` 字段 + 与 `raw_text` 的界限 docstring |
+| `transports/_http_errors.py` | **新建**:`summarize_body` / `response_body` / `_ERROR_BODY_CAP` |
+| `transports/openai_compat.py` | `_status_to_error` 表驱动重写;`_translate_429` 收 `ctx` |
+| `transports/monkey_ocr.py` | `_classify_status` 带摘要 |
+| `errors.py` docstring + `ARCHITECTURE.md` §6.2 | 中转拓扑下 400 的提醒(§5.2) |
+| `README.md:34` | 安装 pin `==1.1.*` → `>=1.2,<2`(§5.3,发布前置,漏改则下游拿不到本修复) |
+
+三个调用点(`openai_compat.py:402` embed、`:417` stream、`:509` 非流式)**签名不变**,无需改动。
+
+## 4. 非功能维度
+
+### 4.1 并发与取消
+
+新增全部是纯函数与数据字段,无状态、无锁、无 IO、不引入 `await`。`response_body` 只读已缓冲字节,`ResponseNotRead` 时直接返回空串而**不发起网络读**——否则会在错误路径上凭空插入一次可能挂住的 IO。`CancelledError` 路径逐字不变。
+
+### 4.2 降级方向
+
+响应体不可得(未读缓冲 / 解码失败 / 空体)→ `body_text=""`,**静默降级,绝不报错**。诊断信息属可观测性,按库铁律与缓存/遥测同档:缺了降级,不得把一次本可正确分类的失败变成不可分类的崩溃。流式路径的 `(await resp.aread()).decode("utf-8", errors="replace")`(`:416`)已是这个口径,保持。
+
+### 4.3 幂等与重复
+
+纯函数,同输入同输出。`summarize_body` 对自身输出再调用一次是幂等的:输出总长恒为 `2000 + len(标记) ≤ 2048`(标记形如 `…(略 N 字)…`,8 + N 的位数,现实中远不足 48),且不含需折叠的空白,故第二次调用走"原样返回"分支,不会出现标记被反复嵌套。
+
+### 4.4 持久化与原子性
+
+不新增表、不改 DDL、不动遥测端口的 22 字段与列序。摘要经既有 `error TEXT` 列落盘,原子性由既有单行写入保证。
+
+### 4.5 安全与体积
+
+- **响应体可能回显请求内容**(部分网关的 `error.param` 会带违规字段值)。截断 + 空白折叠是主要止血手段;字段 docstring 须写明"可能包含请求回显,已截断"。库不做内容脱敏——库不知道下游哪些字段敏感,猜测式脱敏只会同时丢掉诊断价值与安全性。
+- **本设计不放大既有的读取风险**:`_complete_stream:416` 的 `aread()` 对错误响应体无大小上限(超大错误体可打爆内存),该风险今天已经存在(读完即丢),留存后只是更显眼。**不夹带修复**,见 §5.4。
+
+## 5. 错误处理、语义与边界
+
+### 5.1 错误分类
+
+不改任何映射。`body_text` 是**旁路数据**,不参与任何治理判定——不影响重试、换源、熔断计数、AIMD、限流结算。这是本设计能与 ARCHITECTURE §6.1/§6.2 零冲突的根本原因。
+
+### 5.2 400 语义:不改行为,补文档
+
+Issue 报告了一个有说服力的观察:同字节 15 次重发全部成功、`prompt_tokens=0`、耗时 2996ms 远低于同批 631 次成功调用的最快值 7366ms——说明那次 400 来自中转服务自身抖动,而非"你的输入有问题"。
+
+**仍不改分类**:400 重试对直连供应商是纯浪费(确定性坏输入,重试只烧配额并拖延失败);"中转也回 400"是**部署拓扑**引入的信息损失,库从状态码无从分辨。默认改为可重试 = 让所有直连用户为一种部署形态买单,且推翻已冻结的公共契约。
+
+**但本设计本身就是对这个观察最好的答复**:body 留存后,下游能自己区分——中转抖动的 400 体与供应商 `invalid_request_error` 体形态不同。库不替下游做判断,而是把判断所需的信息交出去。配套文档动作:`RequestRejectedError` docstring 与 ARCHITECTURE §6.2 各加一句"经中转部署时 400 可能源于中转自身抖动,批处理场景下游宜自备兜底分类"。
+
+### 5.3 兼容性
+
+`LLMResponse` 一族的"字段只增不删不改名"约束(ARCHITECTURE §5.1)同样适用于异常。本次是**纯新增关键字参数且带默认值**:既有构造点、既有 `except` 写法、既有 `str(exc)` 消费方全部不受影响。message 文本变化不构成破坏——现有测试对这些 message 无格式依赖(仅 `test_openai_compat.py:558` match 源名)。
+
+版本 **1.2.0**(公共类型新增字段属 minor;2026-08-16 人类定夺)。
+
+**发布时必须同步改 README 的安装 pin**:`README.md:34` 现为 `"polygateway[redis,postgres,structured]==1.1.*"`,发 1.2.0 后照此命令安装的下游会**静默停在 1.1.2**——无报错、无警告,与 CLAUDE.md §4.4.1 点名的"极易漏改"完全同款(registry 长期停在 1.0.5 即此类事故)。本次改为 **`>=1.2,<2`**,把"每发一个 minor 就要通知三个下游改 pin"这一反复出现的麻烦一次性消除。此项列入实现计划的发布前置步骤,不是发布日的临时动作。
+
+### 5.4 有意不夹带的两项(建议单开 issue)
+
+| 项 | 说明 |
+|---|---|
+| `_status_to_error` 的 `operation` 硬编码 `"chat"`(`:134`),而 `embed()` 也调它(`:402`) | embedding 的 HTTP 错误在遥测里被标成 `operation="chat"`,是既有数据正确性缺陷,与本 issue 无关 |
+| `_complete_stream:416` 的 `aread()` 无大小上限 | 恶意/故障网关的超大错误体可打爆内存,属独立的健壮性问题 |
+
+两项都在本次重构触及的函数附近,但修它们既不服务 G1-G4,也各自需要独立的行为讨论——按反 gold-plating 铁律留给独立 issue。
+
+## 6. 被否决的路线
+
+### 6.1 给遥测端口加一列(22 → 23 字段)
+
+最"正统"的结构化留存,但成本极不相称:端口 Protocol 签名变更 + SQLite/Postgres 双后端 DDL 迁移 + 下游已有表的 ALTER + 列序契约测试全线改动——为一个诊断串付出一次跨三项目的迁移。而复用既有 `error TEXT` 列可达成同样的可查证性。
+
+### 6.2 只在 `_status_to_error` 打一条 WARNING 日志(Issue 方向二)
+
+不采纳为**主**手段:日志与遥测是两套留存,日志轮转后仍然查不到,而 Issue 的痛点恰是"事后"。且库铁律要求库不擅自向下游日志流写入高频内容(4xx/5xx 在批处理下可能极高频)。message 携带摘要已让 loguru 侧的下游在捕获点自然拿到同一份信息,再加一条独立日志属重复留存。
+
+### 6.3 截断放在异常构造器内
+
+构造器自动规范化更"防遗漏",但会让下游自建异常时传入的文本被悄悄改写,违反 P4;且 message 里的摘要仍需在翻译层单独算一次,反而出现两条规范化路径。选定方案在翻译层算一次、两处共用,更简且更显式。
+
+### 6.4 错误分类映射可插拔(provider profile 注入 classifier)
+
+Issue 的中转 400 场景确实指向这个方向,但当前只有一个使用方且他们已用自己的兜底分类解决。`ProviderProfile`(`providers.py:17-45`)目前也没有这个扩展点,加它是新子系统级的设计。YAGNI:等第二个使用方提出。
+
+## 7. 测试策略(先失败后通过)
+
+**验收主张**:一次 400 调用后,注入的 recorder 收到的 `error` 串含网关响应体摘要。这条端到端断言直接对应 Issue 的痛点,是本设计成立与否的唯一硬判据;其余为覆盖性用例。
+
+| # | 用例 | 覆盖 |
+|---|---|---|
+| 1 | **端到端遥测**:mock transport 返回 400 + 真实样本体 → 断言 recorder 收到的 `error` 含摘要 | G1 |
+| 2 | 参数化状态码(400 / 401 / 404 兜底 / 429 普通 / 429 `insufficient_quota` / 500)→ 断言 message 含摘要且 `exc.body_text` 非空,**分类与既有断言逐一不变** | G2, G4 |
+| 3 | 超长体 → 前 1400 字符与原文头部逐字相同、**末 600 字符与原文尾部逐字相同**、中段为 `…(略 N 字)…` 且 N 等于实际省略数;`body_text` 与 message 中的摘要逐字相同 | G3 |
+| 3b | 长度恰为 2048 / 2049 的体 → 前者原样无标记,后者走头尾保留(边界) | §3.4 |
+| 3c | **尾部关键字段可见**:以 issue 的真实样本尾部 `"code":"invalid_parameter_error"}}` 构造超长体 → 断言该串出现在摘要中 | §3.4 头尾决策的验收 |
+| 3d | 摘要对自身幂等(再摘要一次不嵌套标记) | §4.3 |
+| 4 | 多行缩进 JSON → 折叠为单行 | G3 |
+| 5 | 空体 / 纯空白体 → 不拼悬空分隔符,`body_text == ""` | §3.3 |
+| 6 | 非 JSON 体、非 UTF-8 字节 → 不抛异常,分类不变 | §4.2 |
+| 7 | 流式错误路径(`_complete_stream` 415-417)同样带摘要 | G2 |
+| 8 | `monkey_ocr._classify_status` 同款(含 `ResponseNotRead` 时降级为空串而非抛出) | G2, §4.2 |
+| 9 | embedding 路径(`:402`)HTTP 错误带摘要 | G2 |
+
+`tests/unit/test_errors.py:29` 现有的"四类构造形态"参数化用例需扩展 `body_text` 默认值断言(默认 `""`、可传入、`GatewayUnavailableError` 一族恒空)。
+
+## 8. 人类定夺记录(2026-08-16)
+
+| 议题 | 定夺 |
+|---|---|
+| 摘要上限与保留策略 | 初稿 500 + 头部硬切被否:上限提至 **2048**(对齐 k8s client-go 同场景先例),策略改为**头 1400 + 尾 600 + 省略字数标记**——人类指出"有用的信息可能只在后半部分",经调研证实 JSON 错误体的 `code`/`request_id` 确实收尾(§3.4、§3.4.1) |
+| 429 是否设例外 | **不设**,一律拼摘要(§3.3) |
+| 版本 | **1.2.0**,并同步把 README pin 由 `==1.1.*` 改为 `>=1.2,<2`(§5.3) |
diff --git a/research-wiki/designs/issue10-error-body-retention.md b/research-wiki/designs/issue10-error-body-retention.md
new file mode 100644
index 0000000..c05b294
--- /dev/null
+++ b/research-wiki/designs/issue10-error-body-retention.md
@@ -0,0 +1,62 @@
+---
+type: design
+node_id: design:issue10-error-body-retention
+title: "HTTP 错误响应体留存(Issue #10)"
+date: 2026-08-16
+---
+
+# HTTP 错误响应体留存(Issue #10)
+
+**来源**: Gitea issue #10(CHSAnalyzer3 现场,1050 张影像批处理中 1 张 400 被判确定性失败、事后无从查证)|**范围**: `errors.py` + 两个 transport|**全文**: `designs/2026-08-16-issue10-error-body-retention-design.md`|**相关**: [[design:issue8-stall-budget]](同为下游实测反馈驱动的治理修正)
+
+## 问题
+
+网关拒绝一次调用时,它说的话在 transport 翻译层被丢弃,进程中不再有任何副本:该模块无 logger、异常类无承载字段、库遥测只写 message。三条留存通道同时为空,故"永久查不到"。
+
+## 根因(Issue 前提的关键修正)
+
+Issue 建议"给异常加 `body_text` 字段,下游就能记进遥测"——**只做这一半解决不了它自己陈述的痛点**。库的逐次遥测写的是 `error=str(exc)`(`retry.py:552` → `telemetry.py` → `sqlite.py` 的 `error TEXT` 列),即**异常 message**;新增字段不进库的遥测表。下游说的"写进遥测表"是他们自己的埋点。
+
+缺陷范围也大于 issue 所述:实为 6 处同构——`_status_to_error` 的 400 / 4xx 兜底 / 401·403 / 5xx 四支,`_translate_429` 两支(读了 body 判类型却不带),以及 `monkey_ocr._classify_status` 全部分支(message 只有 `HTTP {status}`)。Issue 场景"读表格"极可能正落在 OCR 路径。
+
+## 选定方案
+
+**摘要在翻译层算一次,同一份串同时进 message 与新增的基类字段**——前者解决"事后可查"(走既有遥测列,零 DDL),后者解决下游结构化留存。
+
+| 决策 | 理由 |
+|---|---|
+| 字段加在 `PolyGatewayError` 基类,非 `RequestRejectedError` | 这些错误全由同一个 HTTP 响应翻译而来,"对方说了什么"与"属于哪一类"正交;只加子类,下次给 `SourceDeadError` 加又是一次公共 API 变更 + 人类门 |
+| 与 `ResultInvalidError.raw_text` 的界限写进 docstring | `body_text` = 非 2xx 的拒绝理由;`raw_text` = 2xx 但不可解析的模型输出。两个"原文字段"不钉死必被混用 |
+| 新建 `transports/_http_errors.py` 共用摘要口径 | 两 transport 各有分类逻辑(OCR 无 429 细分,有意保留),但摘要必须同一份,否则就是下一个"只修一半" |
+| `_status_to_error` 改表驱动 | 五分支各拼各的 message,加摘要即五处重复;查表 + 单点拼装后代码更短 |
+| 摘要 = 折叠空白 + 总长 ≤ 2048,超出则**保留头 1400 + 尾 600**,中段记省略字数 | 折叠是因错误体常是缩进 JSON,拼进 message 会炸成多行。2048 对齐 k8s client-go 的 `maxUnstructuredResponseTextBytes`(唯一同场景先例);**头尾保留取自 `reprlib`**——JSON 错误体的 `code`/`request_id` 收尾,头部硬切正好切掉向网关追查唯一有用的部分(人类质疑 + 2026-08-16 调研,初稿的 500 + 头部硬切已废) |
+| 429 不设例外 | 例外就是下一个复发点;`insufficient_quota` 那支的配额细节全在 body 里 |
+| 400 治理语义不动,只补文档 | 见下 |
+
+## 400 语义:不改行为,本次修复本身就是答复
+
+Issue 给出有力证据(同字节 15 次重发全成功、`prompt_tokens=0`、2996ms 远低于同批成功最快的 7366ms),说明那次 400 来自中转服务抖动而非坏输入。**仍不改分类**:400 重试对直连供应商是纯浪费,而"中转也回 400"是部署拓扑引入的信息损失,库从状态码无从分辨;默认改可重试 = 让所有直连用户为一种部署形态买单。
+
+但 body 留存后**下游能自己区分**——中转抖动体与供应商 `invalid_request_error` 体形态不同。库不替下游判断,把判断所需的信息交出去。配套在 docstring 与 ARCHITECTURE §6.2 加一句中转拓扑提醒。
+
+## 被否决的备选
+
+| 备选 | 否决理由 |
+|---|---|
+| 遥测端口加一列(22 → 23 字段) | 端口签名变更 + 双后端 DDL + 下游 ALTER + 列序契约全线改动,为一个诊断串付出跨三项目迁移;复用既有 `error` 列可达成同样可查证性 |
+| 只打一条 WARNING 日志(issue 方向二) | 日志轮转后仍查不到,而痛点恰是"事后";且 4xx/5xx 在批处理下可能极高频 |
+| 截断放进异常构造器 | 下游自建异常的文本被悄悄改写(违反 P4),且 message 侧仍需单独算一次,反出现两条规范化路径 |
+| 错误分类映射可插拔 | Issue 场景确实指向它,但当前只有一个使用方且已用自己的兜底分类解决;`ProviderProfile` 无此扩展点,加它是子系统级设计。YAGNI |
+
+## 有意不夹带(留独立 issue)
+
+- `_status_to_error` 的 `operation` 硬编码 `"chat"`,而 `embed()` 也调它 → embedding 的 HTTP 错误在遥测里被标成 chat。
+- `_complete_stream` 的 `aread()` 对错误响应体无大小上限,超大错误体可打爆内存(既有风险,留存后更显眼)。
+
+两项都在本次触及的函数附近,但均不服务本 issue 目标,且各需独立行为讨论。
+
+## 验收主张
+
+一次 400 调用后,注入的 recorder 收到的 `error` 串含网关响应体摘要——这条端到端断言是本设计成立与否的唯一硬判据,其余用例为覆盖性(状态码参数化、截断边界 2048/2049、**尾部关键字段可见**、空白折叠、空体不拼悬空分隔符、非 UTF-8 不炸、流式路径、OCR 路径含 `ResponseNotRead` 降级)。
+
+**发布约束**:版本 1.2.0,且 README 安装 pin 必须由 `==1.1.*` 改为 `>=1.2,<2`——否则照 README 安装的下游静默停在 1.1.2,拿不到本修复。
diff --git a/research-wiki/graph/edges.json b/research-wiki/graph/edges.json
index 0df7778..871ad31 100644
--- a/research-wiki/graph/edges.json
+++ b/research-wiki/graph/edges.json
@@ -150,6 +150,16 @@
       "id": "plan:issue8-stall-budget-plan",
       "label": "issue #8 实施计划: stall 非生产性等待口径",
       "type": "plan"
+    },
+    {
+      "id": "design:issue10-error-body-retention",
+      "label": "HTTP 错误响应体留存(Issue #10)",
+      "type": "design"
+    },
+    {
+      "id": "plan:issue10-error-body-retention-plan",
+      "label": "实现计划: HTTP 错误响应体留存(Issue #10)",
+      "type": "plan"
     }
   ],
   "links": [
@@ -271,6 +281,13 @@
       "relation": "implements",
       "evidence": "T1-T6 实施该设计,含 §3.6 订正",
       "added": "2026-08-06T14:58:01.673693+00:00"
+    },
+    {
+      "source": "plan:issue10-error-body-retention-plan",
+      "target": "design:issue10-error-body-retention",
+      "relation": "implements",
+      "evidence": "7 任务覆盖设计 G1-G4 与 §7 全部验收用例",
+      "added": "2026-08-16T09:50:57.830855+00:00"
     }
   ]
 }
\ No newline at end of file
diff --git a/research-wiki/index.md b/research-wiki/index.md
index 47f7e61..c72c94b 100644
--- a/research-wiki/index.md
+++ b/research-wiki/index.md
@@ -1,8 +1,8 @@
 # Research Wiki 索引
 
-> 自动生成，更新时间：2026-08-07 15:11 UTC
+> 自动生成，更新时间：2026-08-16 09:50 UTC
 
-## design (26)
+## design (28)
 - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
 - [2026-07-20-m2-distributed-design](designs/2026-07-20-m2-distributed-design.md) `design:2026-07-20-m2-distributed-design`
 - [2026-07-21-m25-resilience-design](designs/2026-07-21-m25-resilience-design.md) `design:2026-07-21-m25-resilience-design`
@@ -15,9 +15,11 @@
 - [2026-07-31-sampling-params-design](designs/2026-07-31-sampling-params-design.md) `design:2026-07-31-sampling-params-design`
 - [2026-08-06-governance-backend-error-design](designs/2026-08-06-governance-backend-error-design.md) `design:2026-08-06-governance-backend-error-design`
 - [2026-08-06-issue8-stall-budget-design](designs/2026-08-06-issue8-stall-budget-design.md) `design:2026-08-06-issue8-stall-budget-design`
+- [2026-08-16-issue10-error-body-retention-design](designs/2026-08-16-issue10-error-body-retention-design.md) `design:2026-08-16-issue10-error-body-retention-design`
 - [est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2)](designs/est-tokens-decoupling.md) `design:est-tokens-decoupling`
 - [GatewaySettings 装配校验补齐(第二轮)](designs/settings-invariants-round-2.md) `design:settings-invariants-round-2`
 - [GatewaySettings 跨字段不变量守卫的生效范围](designs/settings-invariant-guards.md) `design:settings-invariant-guards`
+- [HTTP 错误响应体留存(Issue #10)](designs/issue10-error-body-retention.md) `design:issue10-error-body-retention`
 - [M1 核心里程碑设计:公共签名冻结与治理栈落地](designs/m1-core-design.md) `design:m1-core-design`
 - [M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness](designs/m2-distributed.md) `design:m2-distributed`
 - [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`
@@ -44,7 +46,7 @@
 - [P7 OCR soak 验收: 99.73% 与 13 不变量全 PASS](findings/p7-ocr-soak.md) `finding:p7-ocr-soak`
 - [推理开关与 reasoning_tokens: 供应商实测与业界做法](findings/2026-08-02-thinking-switch-and-reasoning-tokens.md) `finding:2026-08-02-thinking-switch-and-reasoning-tokens`
 
-## plan (21)
+## plan (23)
 - [2026-07-20-m1-core-plan](plans/2026-07-20-m1-core-plan.md) `plan:2026-07-20-m1-core-plan`
 - [2026-07-20-m2-distributed-plan](plans/2026-07-20-m2-distributed-plan.md) `plan:2026-07-20-m2-distributed-plan`
 - [2026-07-21-m25-resilience-plan](plans/2026-07-21-m25-resilience-plan.md) `plan:2026-07-21-m25-resilience-plan`
@@ -55,6 +57,7 @@
 - [2026-07-31-sampling-params](plans/2026-07-31-sampling-params.md) `plan:2026-07-31-sampling-params`
 - [2026-08-06-governance-backend-error-plan](plans/2026-08-06-governance-backend-error-plan.md) `plan:2026-08-06-governance-backend-error-plan`
 - [2026-08-06-issue8-stall-budget](plans/2026-08-06-issue8-stall-budget.md) `plan:2026-08-06-issue8-stall-budget`
+- [2026-08-16-issue10-error-body-retention](plans/2026-08-16-issue10-error-body-retention.md) `plan:2026-08-16-issue10-error-body-retention`
 - [est_tokens 解耦实施计划](plans/est-tokens-decoupling.md) `plan:est-tokens-decoupling`
 - [issue #8 实施计划: stall 非生产性等待口径](plans/issue8-stall-budget-plan.md) `plan:issue8-stall-budget-plan`
 - [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan`
@@ -63,6 +66,7 @@
 - [M3 OCR 实现计划](plans/m3-ocr.md) `plan:m3-ocr`
 - [M4 迁移实现计划(T0-T14)](plans/m4-migration.md) `plan:m4-migration`
 - [响应可观测字段扩展实现计划](plans/response-observability-fields.md) `plan:response-observability-fields`
+- [实现计划: HTTP 错误响应体留存(Issue #10)](plans/issue10-error-body-retention-plan.md) `plan:issue10-error-body-retention-plan`
 - [实现计划: 治理后端故障归位为 scope 级不可用(Issue #7)](plans/governance-backend-error.md) `plan:governance-backend-error`
 - [推理开关能力建模与 reasoning_tokens 采集实施计划(issue #5 + #6)](plans/2026-08-02-thinking-capability.md) `plan:2026-08-02-thinking-capability`
 - [采样参数透传实现计划(issue #4)](plans/sampling-params-plan.md) `plan:sampling-params-plan`
diff --git a/research-wiki/log.md b/research-wiki/log.md
index 2b8a376..a83a4a9 100644
--- a/research-wiki/log.md
+++ b/research-wiki/log.md
@@ -97,3 +97,8 @@
 - [2026-08-07 15:20 UTC] 新增 design: 建表前先探测,判死只认「确定写不进去」 (design:issue9-telemetry-ddl-probe)
 - [2026-08-07 15:20 UTC] 重建索引: 62 篇页面
 - [2026-08-07 15:11 UTC] 重建索引: 62 篇页面
+- [2026-08-16 09:09 UTC] 新增 design: HTTP 错误响应体留存(Issue #10) (design:issue10-error-body-retention)
+- [2026-08-16 09:12 UTC] 重建索引: 64 篇页面
+- [2026-08-16 09:50 UTC] 新增 plan: 实现计划: HTTP 错误响应体留存(Issue #10) (plan:issue10-error-body-retention-plan)
+- [2026-08-16 09:50 UTC] 新增边: plan:issue10-error-body-retention-plan --implements--> design:issue10-error-body-retention
+- [2026-08-16 09:50 UTC] 重建索引: 66 篇页面
diff --git a/research-wiki/plans/2026-08-16-issue10-error-body-retention.md b/research-wiki/plans/2026-08-16-issue10-error-body-retention.md
new file mode 100644
index 0000000..efeda27
--- /dev/null
+++ b/research-wiki/plans/2026-08-16-issue10-error-body-retention.md
@@ -0,0 +1,259 @@
+# 实现计划: HTTP 错误响应体留存(Issue #10)
+
+- **设计**: `research-wiki/designs/2026-08-16-issue10-error-body-retention-design.md`(**已批准 2026-08-16**)
+- **分支**: `feat/issue-10-error-body-retention`
+- **目标**: 网关拒绝一次调用时,它说的话必须能在库自己的遥测表里被事后查到。
+- **方案概述**: transport 翻译层把 HTTP 错误响应体折叠空白并按头尾策略摘要,**同一份串**同时拼进异常 message(经既有 `error` 列落遥测)与新增的基类字段 `body_text`(供下游结构化留存)。覆盖两个 transport 的全部非 2xx 分支。不改任何状态码→分类的映射。
+- **涉及技术**: Python 3.11 / httpx / pytest。无新增依赖。
+- **保真校验**: 本计划**不涉及** `reference/` 参考实现迁移——错误分类映射逐条不变,保真体现为"既有分类断言全部保留、无一条被改写"(Task 3/4 验收项)。
+
+## 文件结构
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `src/polygateway/errors.py` | 改 | 基类 `PolyGatewayError` 新增 `body_text` 字段;与 `raw_text` 的界限 docstring;`RequestRejectedError` 补中转拓扑提醒 |
+| `src/polygateway/transports/_http_errors.py` | **新建** | 摘要口径单一实现:`summarize_body` / `compose_message` / `response_body` + 三个常量 |
+| `src/polygateway/transports/openai_compat.py` | 改 | `_status_to_error` 表驱动重写;`_translate_429` 收 `ctx` |
+| `src/polygateway/transports/monkey_ocr.py` | 改 | `_classify_status` 带摘要 |
+| `tests/unit/test_http_error_body.py` | **新建** | 摘要单元的纯函数用例(截断边界、头尾保留、折叠、幂等) |
+| `tests/unit/test_openai_compat.py` | 改 | 状态码参数化断言 message + 字段;超长 `insufficient_quota` 回归 |
+| `tests/unit/test_monkey_ocr.py` | 改 | OCR 分支同款 + `ResponseNotRead` 降级 |
+| `tests/unit/test_errors.py` | 改 | `body_text` 默认值与可传性 |
+| `tests/integration/test_governance_stack.py` | 改 | **端到端验收**:400 调用后 SQLite `error` 列含摘要 |
+| `README.md` / `CHANGELOG.md` / `pyproject.toml` / `src/polygateway/__init__.py` / `research-wiki/ARCHITECTURE.md` | 改 | 文档与 1.2.0 版本号 |
+
+## 关键接口(跨任务消费,必须逐字一致)
+
+```python
+# src/polygateway/transports/_http_errors.py
+from __future__ import annotations
+
+import httpx                      # response_body 的类型与 ResponseNotRead 都来自它
+
+_ERROR_BODY_CAP = 2048   # 字符(非字节),含省略标记在内的最终总长上限
+_HEAD_CHARS = 1400
+_TAIL_CHARS = 600
+
+
+def summarize_body(text: str) -> str:
+    """折叠空白后按头尾策略摘要;空/空白入参返回空串。"""
+    collapsed = " ".join(text.split())
+    if len(collapsed) <= _ERROR_BODY_CAP:
+        return collapsed
+    omitted = len(collapsed) - _HEAD_CHARS - _TAIL_CHARS
+    return f"{collapsed[:_HEAD_CHARS]}…(略 {omitted} 字)…{collapsed[-_TAIL_CHARS:]}"
+
+
+def compose_message(message: str, summary: str) -> str:
+    """摘要非空才拼后缀,避免悬空分隔符。"""
+    return f"{message} | {summary}" if summary else message
+
+
+def response_body(response: httpx.Response) -> str:
+    """取已缓冲的响应文本;未读缓冲一律降级空串,绝不触发网络读。"""
+    try:
+        return response.text
+    except httpx.ResponseNotRead:
+        return ""
+```
+
+```python
+# src/polygateway/errors.py
+class PolyGatewayError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        source_name: str | None = None,
+        status_code: int | None = None,
+        operation: str | None = None,
+        body_text: str = "",
+    ) -> None:
+```
+
+```python
+# src/polygateway/transports/openai_compat.py
+# 既有 errors 导入(:18-23)须补入 PolyGatewayError —— 当前只导了四个子类,
+# 直接写 _classify 的返回注解会让 ruff 报 F821 未定义名。
+from polygateway.errors import (
+    PolyGatewayError,          # ← 新增
+    RequestRejectedError,
+    ResultInvalidError,
+    SourceDeadError,
+    TransientError,
+)
+from polygateway.transports._http_errors import compose_message, summarize_body
+
+
+def _classify(status: int) -> tuple[type[PolyGatewayError], str]:
+    """状态码 → (错误类, message 标签);映射与 1.1.2 逐条相同。"""
+    if status in (401, 403):
+        return SourceDeadError, "凭据失效/欠费"
+    if status == 400:
+        return RequestRejectedError, "请求被拒"
+    if status >= 500:
+        return TransientError, "瞬时错误"
+    return RequestRejectedError, "客户端错误"
+
+
+def _status_to_error(
+    source: SourceConfig, status: int, body_text: str, headers: Mapping[str, str]
+) -> Exception:
+    summary = summarize_body(body_text)          # 全函数只算一次
+    ctx: dict[str, Any] = {
+        "source_name": source.name,
+        "status_code": status,
+        "operation": "chat",
+        "body_text": summary,
+    }
+    if status == 429:
+        return _translate_429(source, body_text, headers, ctx)   # 传**原文**,见下
+    cls, label = _classify(status)
+    return cls(compose_message(f"{source.name} {label}: {status}", summary), **ctx)
+```
+
+> **实现红线**:`_translate_429` 判 `insufficient_quota` 必须解析**未截断的原文** `body_text`,不得改用 `summary`。摘要会破坏 JSON 结构,超长体一旦改用摘要解析,配额耗尽的源将不再 `force_open`——那是把一个诊断改进变成治理 bug。Task 3 有专门的回归用例钉死这条。
+
+## 任务清单
+
+### - [ ] Task 1: 内核新增 `body_text` 字段
+
+**改**: `src/polygateway/errors.py`
+
+- `PolyGatewayError.__init__` 按上文签名新增 `body_text: str = ""`,存为实例属性。
+- 类 docstring 增补与 `ResultInvalidError.raw_text` 的界限:`body_text` = 非 2xx 的 HTTP 错误响应体摘要(对方拒绝的理由);`raw_text` = 2xx 但内容不可解析时的模型输出。并写明"可能包含请求回显,已截断"。
+- **不动** `TransientError` / `SourceDeadError` / `RequestRejectedError` / `ResultInvalidError` / `GatewayUnavailableError` 的任何既有签名与行为。
+
+**测试**(`tests/unit/test_errors.py`,扩展 `:29` 的四类构造形态参数化):
+- 四个 transport 错误类默认 `body_text == ""`;显式传入后可读回。
+- `GatewayUnavailableError` / `CircuitOpenError` / `AllSourcesExhausted` / `GovernanceBackendError` 的 `body_text` 恒为 `""`(它们不经 HTTP 响应翻译)。
+
+**验收**: 新增字段不改变任何既有异常的 `str()` 输出。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_errors.py -v` → 全 PASS。
+
+### - [ ] Task 2: 共享摘要单元
+
+**新建**: `src/polygateway/transports/_http_errors.py`(按上文"关键接口"逐字实现,**含其中的 `import httpx`**,加中文模块/函数 docstring 解释**为什么**折叠空白、为什么头尾保留、为什么 `response_body` 必须降级)
+
+**新建测试**: `tests/unit/test_http_error_body.py`
+
+| 用例 | 断言 |
+|---|---|
+| 短体原样 | `summarize_body('{"a":1}') == '{"a":1}'` |
+| 空白折叠 | 多行缩进 JSON → 单行,无连续空格 |
+| 空 / 纯空白入参 | 返回 `""` |
+| 长度恰 2048 | 原样返回,无标记 |
+| 长度 2049 | 走头尾策略 |
+| 超长体头尾 | 前 1400 字符 == 原文前 1400;**末 600 字符 == 原文末 600**;中段标记内 N == `len(原文) - 2000` |
+| **尾部关键字段可见**(设计 §7 用例 3c) | 以 issue 真实样本尾部 `"code":"invalid_parameter_error"}}` 收尾构造超长体 → 断言该串出现在摘要中 |
+| 幂等 | `summarize_body(summarize_body(x)) == summarize_body(x)`(标记不嵌套) |
+| `compose_message` | 摘要为空时返回原 message 不变;非空时以竖线分隔符拼接 |
+| `response_body` 降级 | `httpx.Response(400, stream=<未读 SyncByteStream>)` → 返回 `""` 且不抛(构造法见下) |
+
+未读响应的构造(已实测可用):
+
+```python
+class _Unread(httpx.SyncByteStream):
+    def __iter__(self):
+        yield b"body"
+
+resp = httpx.Response(400, stream=_Unread())   # 未 read → .text 抛 ResponseNotRead
+```
+
+**验收**: 摘要总长恒 ≤ `2000 + len(标记)`;头尾各自与原文逐字对应。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_http_error_body.py -v` → 全 PASS。
+
+### - [ ] Task 3: openai_compat 翻译层收口
+
+**改**: `src/polygateway/transports/openai_compat.py`
+
+- 新增 `_classify`,`_status_to_error` 按上文骨架重写(五分支各拼各的 message → 查表 + 单点拼装)。
+- `_translate_429` 签名改为 `(source, body_text, headers, ctx)`,两支 message 各自追加 `compose_message` 后缀,构造改用 `**ctx`;**`json.loads` 仍读原文 `body_text`**。
+- message 主体逐字保持 1.1.2 原样(`凭据失效/欠费: {status}` / `请求被拒: 400` / `瞬时错误: {status}` / `客户端错误: {status}` / `配额耗尽(insufficient_quota)` / `限速: 429`),只在末尾追加 ` | {摘要}`。
+- 三个调用点(`:402` embed、`:417` stream、`:509` 非流式)签名不变,**不改动**。
+- **补 import**:`PolyGatewayError`(errors)与 `compose_message` / `summarize_body`(`._http_errors`),见上文关键接口——漏补则 `make lint` 报 F821(Codex 审查 2026-08-16 提出)。
+- **不改** `operation` 硬编码 `"chat"`(设计 §5.4 有意留给独立 issue)。
+
+**测试**(`tests/unit/test_openai_compat.py`,沿用既有 `_transport_for(handler)` + `httpx.MockTransport`):
+
+| # | 用例 | 断言 |
+|---|---|---|
+| 3.1 | 状态码参数化 400 / 401 / 403 / 404 / 500 / 503,handler 返回带真实样本体 | 异常类型与 1.1.2 **逐条相同**;message 含摘要;`exc.body_text` == 摘要 |
+| 3.2 | 429 普通限速(body 无 `insufficient_quota`) | `TransientError`,message 含摘要,`retry_after_s` 解析不受影响 |
+| 3.3 | 429 + `insufficient_quota` | `SourceDeadError`,message 含摘要 |
+| 3.4 | **回归红线**:429 + `insufficient_quota` 且 body 长度 > 2048(前置大量填充字段) | 仍判 `SourceDeadError`——证明类型判定读的是原文而非摘要 |
+| 3.5 | 空 body 的 400 | message 无悬空分隔符,`body_text == ""` |
+| 3.6 | 非 JSON body、非 UTF-8 字节 body | 不抛额外异常,分类不变 |
+| 3.7 | 流式路径(handler 对 stream 请求返回 400 + body) | 经 `_complete_stream:415-417` 抛出的异常同样带摘要 |
+| 3.8 | embedding 路径(`transport.embed(...)` 遇 400) | 同样带摘要 |
+
+**验收**: 既有测试零修改通过(除 3.x 新增外);`test_openai_compat.py:558`(match 源名)仍 PASS。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_openai_compat.py -v` → 全 PASS。
+
+### - [ ] Task 4: monkey_ocr 同款收口
+
+**改**: `src/polygateway/transports/monkey_ocr.py`
+
+- `_classify_status`:`summary = summarize_body(response_body(exc.response))`,三支 message 统一经 `compose_message` 追加后缀,`ctx` 带 `body_text=summary`。
+- message 主体保持 `f"{source_name} OCR {operation} HTTP {status}"` 不变。
+- 429/5xx → `TransientError`、401/403 → `SourceDeadError`、其余 → `RequestRejectedError` 的映射**逐条不变**(OCR 无 429 细分是设计有意保留,见模块 docstring `:53-54`)。
+
+**测试**(`tests/unit/test_monkey_ocr.py`):
+- 扩展 `:300` 的状态码参数化:各分支 message 含摘要且 `body_text` 非空,分类不变。
+- `ResponseNotRead` 降级:`exc.response` 为未读流 → `body_text == ""`,message 无悬空分隔符,**分类仍正确**(不得因取 body 失败而改变错误类型或抛出 httpx 异常)。
+
+**验收**: `:195` 与 `:300` 既有断言不被改写。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_monkey_ocr.py -v` → 全 PASS。
+
+### - [ ] Task 5: 端到端遥测验收(**本计划的硬判据**)
+
+**改**: `tests/integration/test_governance_stack.py`
+
+新增用例,沿用既有 `_full_client(handler, telemetry=SQLiteRecorder(...))` 与 `:135` 的 `SELECT error FROM llm_calls` 断言模式:
+
+- handler 对 chat 请求返回 `httpx.Response(400, content=<issue #10 真实样本体>)`。
+- `client.chat(...)` 抛 `RequestRejectedError`(400 不重试不换源,行为不变)。
+- `recorder.close()` 后查 `SELECT error FROM llm_calls`:该行 `error` 串**含样本体里的 `InvalidParameter` 与结尾的 `invalid_parameter_error`**。
+
+真实样本体(取自 issue #10 原文,一字不改):
+
+```json
+{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal and cannot be opened","type":"invalid_request_error","param":"","code":"invalid_parameter_error"}}
+```
+
+**验收**: 这条断言在 Task 1-4 之前**必然失败**(1.1.2 的 `error` 列只有 `"qwen_1 请求被拒: 400"`),之后通过——这就是本 issue 的"先失败后通过"证据主体,执行时须保留失败输出截图/文本进提交说明。
+**验证**: `conda run -n PolyGateway pytest tests/integration/test_governance_stack.py -v` → 全 PASS。
+
+### - [ ] Task 6: 文档与版本
+
+**改**:
+
+| 文件 | 内容 |
+|---|---|
+| `src/polygateway/errors.py` | `RequestRejectedError` docstring 加一句:经中转部署时 400 可能源于中转自身抖动,批处理场景下游宜自备兜底分类(设计 §5.2) |
+| `research-wiki/ARCHITECTURE.md` §6.2 | 同一提醒 + 注明四分类错误自 1.2.0 起携带 `body_text` |
+| `CHANGELOG.md` | 新增 `## 1.2.0(2026-08-16)` 段:行为变更(message 追加摘要 → 遥测 `error` 列变长)、新增字段、不变项(分类映射零变更、错误面零变更) |
+| `README.md:34` | 安装 pin `==1.1.*` → **`>=1.2,<2`**(2026-08-16 人类定夺;漏改则下游静默停在 1.1.2) |
+| `pyproject.toml` + `src/polygateway/__init__.py` | 版本号 `1.1.2` → `1.2.0`,**两处必须一致** |
+
+**验收**: `grep -rn "1\.1\.\*" README.md` 零命中;两处版本号一致。
+**验证**: `conda run -n PolyGateway python -c "import polygateway; print(polygateway.__version__)"` → `1.2.0`。
+
+### - [ ] Task 7: 合并前全量门
+
+1. `make lint`(ruff + import-linter)→ 零违规,**重点确认新建 `transports/_http_errors.py` 未触发洋葱分层契约**。
+2. `make test` 全套件 → 全 PASS,覆盖率不低于既有水平。
+3. 派**全新上下文** verifier subagent 独立验证(CLAUDE.md §3 Phase 2 硬门):逐条核对 Task 1-6 验收项与本会话工具输出。
+4. `finishing-a-development-branch` 合并回 main(`--no-ff`),合并后在 main 上重跑 `make lint` 与全套件。
+
+**发布**(合并后)严格按 CLAUDE.md §4.4.1 九步执行,不在本计划展开;其中步骤 1(更新 README)已在 Task 6 前置完成,**构建前须再次确认 pin 已是 `>=1.2,<2`**。
+
+## 执行顺序与提交点
+
+```
+Task 1 ──┐
+         ├── Task 3 ──┐
+Task 2 ──┴── Task 4 ──┴── Task 5 ── Task 6 ── Task 7
+```
+
+Task 1 与 2 可并行(互不依赖);Task 3、4 都依赖 1+2;Task 5 依赖 3;Task 6 独立于代码但须在 Task 7 之前。每个 Task 一次语义化提交(`commit` skill),Task 5 的提交说明须附"修复前失败、修复后通过"的实际输出。
diff --git a/research-wiki/plans/issue10-error-body-retention-plan.md b/research-wiki/plans/issue10-error-body-retention-plan.md
new file mode 100644
index 0000000..a070734
--- /dev/null
+++ b/research-wiki/plans/issue10-error-body-retention-plan.md
@@ -0,0 +1,37 @@
+---
+type: plan
+node_id: plan:issue10-error-body-retention-plan
+title: "实现计划: HTTP 错误响应体留存(Issue #10)"
+date: 2026-08-16
+---
+
+# 实现计划: HTTP 错误响应体留存(Issue #10)
+
+**全文**: `plans/2026-08-16-issue10-error-body-retention.md`|**实现**: [[design:issue10-error-body-retention]]|**分支**: `feat/issue-10-error-body-retention`
+
+## 任务分解
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 1 | 内核字段 | `PolyGatewayError.body_text`(默认空串)+ 与 `raw_text` 的界限 docstring |
+| 2 | 共享摘要单元 | 新建 `transports/_http_errors.py`:`summarize_body` / `compose_message` / `response_body` |
+| 3 | openai_compat 收口 | `_status_to_error` 表驱动;429 判类型仍读原文 |
+| 4 | monkey_ocr 收口 | `_classify_status` 同款,含 `ResponseNotRead` 降级 |
+| 5 | **端到端验收** | 400 调用后 SQLite `error` 列含摘要——本计划的硬判据 |
+| 6 | 文档与版本 | 1.2.0、README pin `>=1.2,<2`、CHANGELOG、ARCHITECTURE §6.2 |
+| 7 | 合并前门 | lint + 全套件 + 全新上下文 verifier |
+
+依赖:1‖2 → 3‖4 → 5 → 6 → 7。
+
+## 计划期钉死的两条实现红线
+
+1. **429 判 `insufficient_quota` 必须解析未截断原文**,不得改用摘要——摘要会破坏 JSON,超长体一旦改用摘要解析,配额耗尽的源将不再 `force_open`,把诊断改进变成治理 bug。Task 3.4 有专门回归用例。
+2. **message 主体逐字保持 1.1.2 原样**,只在末尾追加摘要后缀;状态码→分类映射逐条不变,验收要求既有分类断言零改写。
+
+## 保真校验
+
+不涉及 `reference/` 迁移。错误分类映射不变,保真体现为"既有分类断言全部保留"。
+
+## 执行期观察
+
+Task 计划提交时 pre-commit 钩子的全套件跑出现一次 `tests/e2e/test_compat_projects.py::TestGovDocOnboarding::test_call_site_shape_runs_governed` 失败,单独跑与 e2e 全目录跑(7 passed / 23.30s,每例 2-3.5s)均通过,重跑全套件亦通过 → 判为真实网关抖动,非回归。该用例正是 [[design:issue8-stall-budget]] 当年记录的三个漂移用例之一,e2e 打真实网关的固有 flaky 面仍在。
diff --git a/src/polygateway/__init__.py b/src/polygateway/__init__.py
index 849cab4..96b7873 100644
--- a/src/polygateway/__init__.py
+++ b/src/polygateway/__init__.py
@@ -32,7 +32,7 @@ from polygateway.types import (
     SourceConfig,
 )
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 
 __all__ = [
     "DEFAULT_PROFILES",
diff --git a/src/polygateway/errors.py b/src/polygateway/errors.py
index 1473c91..6fdf8c5 100644
--- a/src/polygateway/errors.py
+++ b/src/polygateway/errors.py
@@ -35,7 +35,26 @@ SOURCE_REASONS = frozenset(
 
 
 class PolyGatewayError(Exception):
-    """库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。"""
+    """库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。
+
+    `body_text` 是**非 2xx 响应体的摘要**——网关拒绝这次调用时说的话(issue #10)。
+    它与 `ResultInvalidError.raw_text` 是两回事,严禁混用:
+
+    ==============  ==================================================
+    ``body_text``   **非 2xx** 的 HTTP 错误响应体: 对方**拒绝**的理由
+    ``raw_text``    **2xx** 但内容不可解析时的模型输出原文
+    ==============  ==================================================
+
+    加在基类而非某个子类,是因为这些错误全部由同一个 HTTP 响应翻译而来——
+    "对方说了什么"与"它属于哪一类"正交。scope 级错误(`GatewayUnavailableError`
+    一族)继承到的恒空值不是噪音,而是"没有单一响应体可言"的如实表达。
+
+    **内容已由 transport 层截断**(`transports/_http_errors.summarize_body`),
+    且可能包含网关对请求的回显——库不做脱敏: 它不知道下游哪些字段敏感,
+    猜测式脱敏只会同时丢掉诊断价值与安全性。
+
+    本字段是**旁路数据**,不参与任何治理判定(重试/换源/熔断计数/限流结算)。
+    """
 
     def __init__(
         self,
@@ -44,11 +63,13 @@ class PolyGatewayError(Exception):
         source_name: str | None = None,
         status_code: int | None = None,
         operation: str | None = None,
+        body_text: str = "",
     ) -> None:
         super().__init__(message)
         self.source_name = source_name
         self.status_code = status_code
         self.operation = operation
+        self.body_text = body_text
 
 
 class TransientError(PolyGatewayError):
@@ -64,7 +85,16 @@ class SourceDeadError(PolyGatewayError):
 
 
 class RequestRejectedError(PolyGatewayError):
-    """请求被拒(400/坏输入): 不重试不换源,直接上抛。"""
+    """请求被拒(400/坏输入): 不重试不换源,直接上抛。
+
+    **经中转部署时请注意**(issue #10 下游实测): 第三方 API 中转服务自身抖动
+    时也会回 400,从状态码上与供应商说"你的输入有问题"无法区分。下游曾观测到
+    同一份字节(sha256 一致)重发 15 次全部成功,且失败那次 `prompt_tokens=0`、
+    耗时远低于任何成功调用——请求在推理开始前就被挡了。本库仍按确定性失败处理
+    (对直连供应商而言重试只会白烧配额),批处理场景的下游宜自备兜底分类;
+    `body_text` 即为此提供判据: 中转抖动的响应体与供应商的 `invalid_request_error`
+    形态不同。
+    """
 
 
 class ResultInvalidError(PolyGatewayError):
diff --git a/src/polygateway/transports/_http_errors.py b/src/polygateway/transports/_http_errors.py
new file mode 100644
index 0000000..f050997
--- /dev/null
+++ b/src/polygateway/transports/_http_errors.py
@@ -0,0 +1,63 @@
+"""HTTP 错误响应体的取用与摘要(issue #10 设计 §3.2)。
+
+两个 transport 各有自己的状态码分类逻辑(OCR 有意不做 429 细分),但**摘要口径
+必须是同一份**——issue #10 的教训正是"只有一个分支用了响应体",一处例外就是
+下一次事后查不到原因。故本模块是全库唯一的摘要实现,不得在别处复制。
+"""
+
+from __future__ import annotations
+
+import httpx
+
+_ERROR_BODY_CAP = 2048
+"""摘要总长上限(**字符**,含省略标记在内)。
+
+取值对齐 Kubernetes client-go `rest/request.go` 的 `maxUnstructuredResponseTextBytes
+= 2048`——它是唯一与本设计同场景(读 HTTP 错误体做诊断)的成熟先例。按字符而非
+字节切,多字节字符不会被切成半个;`error` 列是 TEXT,无定长约束,不需要字节口径。
+"""
+
+_HEAD_CHARS = 1400
+_TAIL_CHARS = 600
+
+
+def summarize_body(text: str) -> str:
+    """折叠空白后按头尾策略摘要;空/空白入参返回空串。
+
+    **折叠空白**不是洁癖: 错误体常是缩进 JSON,原样拼进 message 会把一行日志
+    炸成多行、把遥测列变得不可读。
+
+    **保头保尾**而非头部硬切: 截断的对象是结构化 JSON,信息分布头重尾也重——
+    人话(`message`)在前,机器可判的 `type`/`code`/`param`/`request_id` 在后。
+    k8s/Sentry 用头部硬切是因为它们截的是任意文本;本函数截的是错误 JSON,
+    头部硬切正好切掉向网关方追查时唯一有用的那部分。策略取自标准库 `reprlib`
+    对"给人读的长字符串"的处置。
+
+    **标记记下省略字数**,读的人才知道自己丢了多少,不会误以为网关只说了这么多。
+    """
+    collapsed = " ".join(text.split())
+    if len(collapsed) <= _ERROR_BODY_CAP:
+        return collapsed
+    omitted = len(collapsed) - _HEAD_CHARS - _TAIL_CHARS
+    return f"{collapsed[:_HEAD_CHARS]}…(略 {omitted} 字)…{collapsed[-_TAIL_CHARS:]}"
+
+
+def compose_message(message: str, summary: str) -> str:
+    """摘要非空才拼后缀,避免留下悬空的分隔符。
+
+    分隔符取 ` | ` 而非既有的 `: `,让"库说的话"与"网关说的话"一眼可分。
+    """
+    return f"{message} | {summary}" if summary else message
+
+
+def response_body(response: httpx.Response) -> str:
+    """取**已缓冲**的响应文本;未读缓冲一律降级空串。
+
+    绝不在此触发网络读: 那会在错误路径上凭空插入一次可能挂住的 IO。降级方向
+    与缓存/遥测同档(库铁律)——诊断信息缺失不得把一次本可正确分类的失败变成
+    不可分类的崩溃,那正是 `ResponseNotRead` 泄漏出四分类之外的后果。
+    """
+    try:
+        return response.text
+    except httpx.ResponseNotRead:
+        return ""
diff --git a/src/polygateway/transports/monkey_ocr.py b/src/polygateway/transports/monkey_ocr.py
index e07e990..9e0edc9 100644
--- a/src/polygateway/transports/monkey_ocr.py
+++ b/src/polygateway/transports/monkey_ocr.py
@@ -24,6 +24,11 @@ from polygateway.errors import (
     SourceDeadError,
     TransientError,
 )
+from polygateway.transports._http_errors import (
+    compose_message,
+    response_body,
+    summarize_body,
+)
 from polygateway.types import (
     OcrLayoutElement,
     OcrLayoutTransportResult,
@@ -74,13 +79,20 @@ def _translate_http_errors(source_name: str, operation: str) -> Iterator[None]:
 def _classify_status(
     exc: httpx.HTTPStatusError, source_name: str, operation: str
 ) -> TransientError | SourceDeadError | RequestRejectedError:
+    """HTTP 状态码 → 错误四分类,**全部分支**携带响应体摘要(issue #10)。
+
+    分类映射本身零变更;摘要口径与 chat 侧共用同一实现,不得在此另起一份——
+    "只有一个分支用了响应体"正是 issue #10 的成因。
+    """
     status = exc.response.status_code
+    summary = summarize_body(response_body(exc.response))
     ctx: dict[str, Any] = {
         "source_name": source_name,
         "status_code": status,
         "operation": operation,
+        "body_text": summary,
     }
-    message = f"{source_name} OCR {operation} HTTP {status}"
+    message = compose_message(f"{source_name} OCR {operation} HTTP {status}", summary)
     if status >= 500 or status == 429:
         return TransientError(message, **ctx)
     if status in (401, 403):
diff --git a/src/polygateway/transports/openai_compat.py b/src/polygateway/transports/openai_compat.py
index 2a48a82..d6e8bf2 100644
--- a/src/polygateway/transports/openai_compat.py
+++ b/src/polygateway/transports/openai_compat.py
@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, Any
 import httpx
 
 from polygateway.errors import (
+    PolyGatewayError,
     RequestRejectedError,
     ResultInvalidError,
     SourceDeadError,
@@ -30,6 +31,7 @@ from polygateway.providers import (
     resolve_thinking,
 )
 from polygateway.streaming import StreamLivenessTimeout, stream_with_liveness_timeouts
+from polygateway.transports._http_errors import compose_message, summarize_body
 from polygateway.types import EmbeddingTransportResult, SourceConfig, TransportResult
 
 if TYPE_CHECKING:
@@ -107,40 +109,59 @@ def _parse_retry_after(raw: str | None) -> float | None:
     return seconds if seconds > 0 else None
 
 
-def _translate_429(source: SourceConfig, body_text: str, headers: Mapping[str, str]) -> Exception:
+def _translate_429(
+    source: SourceConfig, body_text: str, headers: Mapping[str, str], ctx: dict[str, Any]
+) -> Exception:
+    """429 细分。`body_text` 必须是**未截断的原文**——`ctx["body_text"]` 是摘要,
+    头尾保留会破坏 JSON 结构,拿它解析会让超长 body 的配额耗尽退化成普通限速
+    (该源不再 force_open),把一个诊断改进变成治理 bug(issue #10 实现红线)。
+    """
     try:
         err_type = json.loads(body_text).get("error", {}).get("type", "")
     except (json.JSONDecodeError, AttributeError):
         err_type = ""
+    summary = ctx["body_text"]
     if err_type == "insufficient_quota":
         return SourceDeadError(
-            f"{source.name} 配额耗尽(insufficient_quota)",
-            source_name=source.name,
-            status_code=429,
-            operation="chat",
+            compose_message(f"{source.name} 配额耗尽(insufficient_quota)", summary), **ctx
         )
     return TransientError(
-        f"{source.name} 限速: 429",
+        compose_message(f"{source.name} 限速: 429", summary),
         retry_after_s=_parse_retry_after(headers.get("retry-after")),
-        source_name=source.name,
-        status_code=429,
-        operation="chat",
+        **ctx,
     )
 
 
+def _classify(status: int) -> tuple[type[PolyGatewayError], str]:
+    """状态码 → (错误类, message 标签);映射与 ARCH §6.2 逐条相同,本次零变更。"""
+    if status in (401, 403):
+        return SourceDeadError, "凭据失效/欠费"
+    if status == 400:
+        return RequestRejectedError, "请求被拒"
+    if status >= 500:
+        return TransientError, "瞬时错误"
+    return RequestRejectedError, "客户端错误"
+
+
 def _status_to_error(
     source: SourceConfig, status: int, body_text: str, headers: Mapping[str, str]
 ) -> Exception:
-    ctx: dict[str, Any] = {"source_name": source.name, "status_code": status, "operation": "chat"}
-    if status in (401, 403):
-        return SourceDeadError(f"{source.name} 凭据失效/欠费: {status}", **ctx)
-    if status == 400:
-        return RequestRejectedError(f"{source.name} 请求被拒: 400", **ctx)
+    """非 2xx → 领域错误,**全部分支**携带响应体摘要(issue #10)。
+
+    摘要只算一次,message 与 `body_text` 共用同一份串: 两份不同长度会让"遥测里
+    看到的"与"下游 catch 到的"对不上,排查时反而多一层困惑。
+    """
+    summary = summarize_body(body_text)
+    ctx: dict[str, Any] = {
+        "source_name": source.name,
+        "status_code": status,
+        "operation": "chat",
+        "body_text": summary,
+    }
     if status == 429:
-        return _translate_429(source, body_text, headers)
-    if status >= 500:
-        return TransientError(f"{source.name} 瞬时错误: {status}", **ctx)
-    return RequestRejectedError(f"{source.name} 客户端错误: {status}", **ctx)
+        return _translate_429(source, body_text, headers, ctx)
+    cls, label = _classify(status)
+    return cls(compose_message(f"{source.name} {label}: {status}", summary), **ctx)
 
 
 def _strip_think(content: str) -> tuple[str, str]:
diff --git a/tests/integration/test_governance_stack.py b/tests/integration/test_governance_stack.py
index 1b31d69..acffbcb 100644
--- a/tests/integration/test_governance_stack.py
+++ b/tests/integration/test_governance_stack.py
@@ -11,7 +11,12 @@ import sqlite3
 import httpx
 import pytest
 
-from polygateway import CircuitOpenError, GatewayClient, TransientError
+from polygateway import (
+    CircuitOpenError,
+    GatewayClient,
+    RequestRejectedError,
+    TransientError,
+)
 from polygateway.backends.memory.breaker import InMemoryGate
 from polygateway.backends.memory.cache import InMemoryCache
 from polygateway.backends.memory.limiter import InMemoryLimiter
@@ -173,6 +178,40 @@ class TestTelemetryAcrossPaths:
         assert len({cid for _, cid in rows}) == 2  # call_id 逐次独立
 
 
+class TestRejectionReasonIsQueryable:
+    """issue #10 的验收主张: 400 之后,网关说的话必须能在遥测表里查到。
+
+    下游一轮 1050 张影像的批处理里,1 张在读表格时收到 400 被判确定性失败,
+    事后"这张图到底哪里不合规"无从查起——响应体在 transport 翻译层就没了。
+    """
+
+    # issue #10 原文给出的真实响应体(一字不改)
+    _BODY = (
+        '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+        'and cannot be opened","type":"invalid_request_error","param":"",'
+        '"code":"invalid_parameter_error"}}'
+    )
+
+    async def test_rejected_call_leaves_the_reason_in_telemetry(self, tmp_path):
+        recorder = SQLiteRecorder(tmp_path / "t.db")
+        client = _full_client(
+            lambda req: httpx.Response(400, content=self._BODY.encode()), telemetry=recorder
+        )
+
+        with pytest.raises(RequestRejectedError):
+            await client.chat([{"role": "user", "content": "hi"}])
+
+        recorder.close()
+        rows = sqlite3.connect(tmp_path / "t.db").execute("SELECT error FROM llm_calls").fetchall()
+        assert rows, "400 必须留下遥测行(遥测必录)"
+        errors = " ".join(r[0] or "" for r in rows)
+        # 修复前这里只有 "qwen_1 请求被拒: 400"——诊断信息一个字都不在
+        assert "InvalidParameter" in errors
+        assert "The image format is illegal" in errors
+        # 尾部的 code 才是向网关方追查的凭据,头部硬切正好会丢掉它
+        assert "invalid_parameter_error" in errors
+
+
 class TestStructuredThroughStack:
     async def test_feedback_reask_passes_through_governance(self):
         """重问经过内层治理: 第二次真实请求同样被限流/熔断记账。"""
diff --git a/tests/unit/test_errors.py b/tests/unit/test_errors.py
index a440f81..ca5646c 100644
--- a/tests/unit/test_errors.py
+++ b/tests/unit/test_errors.py
@@ -34,6 +34,43 @@ class TestBaseShape:
         assert TransientError("429", retry_after_s=2.5).retry_after_s == 2.5
 
 
+class TestBodyText:
+    """issue #10: 非 2xx 的响应体摘要必须有承载处,否则拒绝理由事后不可查。"""
+
+    @pytest.mark.parametrize(
+        "cls", (PolyGatewayError, TransientError, SourceDeadError, RequestRejectedError)
+    )
+    def test_defaults_empty_and_accepts_summary(self, cls):
+        assert cls("boom").body_text == ""
+        assert cls("boom", body_text='{"error":{"code":"bad"}}').body_text == (
+            '{"error":{"code":"bad"}}'
+        )
+
+    def test_result_invalid_keeps_both_fields_apart(self):
+        """`body_text`(非 2xx 的拒绝理由)与 `raw_text`(2xx 的不可解析输出)不得混用。"""
+        exc = ResultInvalidError("bad json", raw_text="{oops", body_text="")
+        assert exc.raw_text == "{oops"
+        assert exc.body_text == ""
+
+    @pytest.mark.parametrize(
+        "exc",
+        (
+            AllSourcesExhausted(scope="llm", reason="stalled", retry_after_s=1.0),
+            CircuitOpenError(scope="llm", retry_after_s=1.0),
+            GovernanceBackendError("redis down", scope="llm"),
+        ),
+    )
+    def test_scope_level_errors_carry_no_body(self, exc):
+        """scope 级失败没有单一响应体可言,空串是如实表达而非噪音。"""
+        assert exc.body_text == ""
+
+    def test_body_text_does_not_leak_into_str(self):
+        """字段是旁路数据: 加了它不得改变任何既有异常的 str() 输出。"""
+        assert str(RequestRejectedError("qwen_1 请求被拒: 400", body_text="whatever")) == (
+            "qwen_1 请求被拒: 400"
+        )
+
+
 class TestResultInvalid:
     def test_carries_diagnosis(self):
         exc = ResultInvalidError(
@@ -134,9 +171,7 @@ class TestGovernanceBackendReason:
         assert "governance_backend_down" in SCOPE_REASONS
 
     def test_gateway_unavailable_accepts_the_new_reason(self):
-        exc = AllSourcesExhausted(
-            scope="LLM", reason="governance_backend_down", retry_after_s=0.0
-        )
+        exc = AllSourcesExhausted(scope="LLM", reason="governance_backend_down", retry_after_s=0.0)
         assert exc.reason == "governance_backend_down"
 
     def test_retry_after_default_is_non_zero(self):
diff --git a/tests/unit/test_http_error_body.py b/tests/unit/test_http_error_body.py
new file mode 100644
index 0000000..b68325a
--- /dev/null
+++ b/tests/unit/test_http_error_body.py
@@ -0,0 +1,89 @@
+"""HTTP 错误响应体摘要口径(issue #10 设计 §3.2/§3.4)。
+
+摘要是 message 与 `body_text` 共用的**同一份串**,故它的边界行为直接决定
+遥测里看到的与下游 catch 到的是否一致——本组用例把规则钉成算术。
+"""
+
+import httpx
+import pytest
+
+from polygateway.transports._http_errors import (
+    _ERROR_BODY_CAP,
+    _HEAD_CHARS,
+    _TAIL_CHARS,
+    compose_message,
+    response_body,
+    summarize_body,
+)
+
+# issue #10 原文给出的真实响应体(一字不改),关键在于 code 收尾
+_REAL_SAMPLE = (
+    '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+    'and cannot be opened","type":"invalid_request_error","param":"",'
+    '"code":"invalid_parameter_error"}}'
+)
+
+
+class TestSummarizeBody:
+    def test_short_body_passes_through(self):
+        assert summarize_body(_REAL_SAMPLE) == _REAL_SAMPLE
+
+    def test_whitespace_collapsed(self):
+        """错误体常是缩进 JSON: 不折叠会把一行日志炸成多行、遥测列不可读。"""
+        assert (
+            summarize_body('{\n  "error": {\n    "code": "x"\n  }\n}')
+            == '{ "error": { "code": "x" } }'
+        )
+
+    @pytest.mark.parametrize("raw", ("", "   ", "\n\t  \n"))
+    def test_blank_yields_empty(self, raw):
+        assert summarize_body(raw) == ""
+
+    def test_exactly_at_cap_is_untouched(self):
+        body = "x" * _ERROR_BODY_CAP
+        assert summarize_body(body) == body
+
+    def test_one_over_cap_is_summarized(self):
+        summary = summarize_body("x" * (_ERROR_BODY_CAP + 1))
+        assert summary != "x" * (_ERROR_BODY_CAP + 1)
+        assert "略" in summary
+
+    def test_head_and_tail_both_survive(self):
+        """头部硬切会丢掉尾部,而 JSON 错误体的 code/request_id 正在尾部。"""
+        body = "H" * 5000 + "T" * 5000
+        summary = summarize_body(body)
+        assert summary[:_HEAD_CHARS] == body[:_HEAD_CHARS]
+        assert summary[-_TAIL_CHARS:] == body[-_TAIL_CHARS:]
+        assert f"…(略 {10000 - _HEAD_CHARS - _TAIL_CHARS} 字)…" in summary
+
+    def test_real_sample_tail_visible_in_oversized_body(self):
+        """设计 §7 用例 3c: 超长体里,追查网关方所需的 code 仍须可见。"""
+        summary = summarize_body("PADDING" * 1000 + _REAL_SAMPLE)
+        assert '"code":"invalid_parameter_error"}}' in summary
+
+    def test_idempotent(self):
+        """再摘要一次不得嵌套标记,否则重复经手的串会层层套娃。"""
+        once = summarize_body("y" * 9999)
+        assert summarize_body(once) == once
+
+
+class TestComposeMessage:
+    def test_empty_summary_leaves_message_intact(self):
+        assert compose_message("qwen_1 请求被拒: 400", "") == "qwen_1 请求被拒: 400"
+
+    def test_non_empty_summary_is_appended(self):
+        assert compose_message("qwen_1 请求被拒: 400", "{}") == "qwen_1 请求被拒: 400 | {}"
+
+
+class TestResponseBody:
+    def test_reads_buffered_text(self):
+        assert response_body(httpx.Response(400, content=b'{"e":1}')) == '{"e":1}'
+
+    def test_unread_stream_degrades_to_empty(self):
+        """取不到诊断信息绝不能升级为崩溃: 未读缓冲返回空串,且不触发网络读。"""
+
+        class _Unread(httpx.SyncByteStream):
+            def __iter__(self):
+                yield b"body"
+
+        assert response_body(httpx.Response(400, stream=_Unread())) == ""
diff --git a/tests/unit/test_monkey_ocr.py b/tests/unit/test_monkey_ocr.py
index 98d59a7..77c4461 100644
--- a/tests/unit/test_monkey_ocr.py
+++ b/tests/unit/test_monkey_ocr.py
@@ -19,7 +19,11 @@ from polygateway.errors import (
     SourceDeadError,
     TransientError,
 )
-from polygateway.transports.monkey_ocr import MonkeyOcrTransport, _parse_middle_json
+from polygateway.transports.monkey_ocr import (
+    MonkeyOcrTransport,
+    _classify_status,
+    _parse_middle_json,
+)
 from polygateway.types import SourceConfig
 
 
@@ -306,6 +310,45 @@ class TestErrorTranslation:
             await t.recognize_text(image=b"jpg", source=_source(), call_id="c1")
         assert ei.value.status_code == status
 
+    @pytest.mark.parametrize(
+        ("status", "exc_type"),
+        [
+            (502, TransientError),
+            (429, TransientError),  # 与 5xx 共用分支,但仍单列: 漏分支正是 issue #10 的成因
+            (401, SourceDeadError),
+            (404, RequestRejectedError),
+        ],
+    )
+    async def test_body_survives_every_branch(self, status, exc_type):
+        """issue #10: OCR 侧 message 原本只有 HTTP 状态码,拒绝理由同样丢失。"""
+        body = '{"detail":"unsupported image mode CMYK"}'
+        t = _transport_for(_routes(text_resp=httpx.Response(status, content=body.encode())))
+        with pytest.raises(exc_type) as ei:
+            await t.recognize_text(image=b"jpg", source=_source(), call_id="c1")
+        assert ei.value.body_text == body
+        assert str(ei.value).endswith(f" | {body}")
+
+    def test_unread_body_degrades_without_changing_class(self):
+        """取不到 body 时降级空串: 绝不能让 ResponseNotRead 逃出错误四分类。
+
+        直接测纯函数而非走 MockTransport——真实客户端对非 stream 请求总会读完
+        响应,未读态只可能在将来给 OCR 加 stream 时出现,而那正是要防的场景。
+        """
+
+        class _Unread(httpx.SyncByteStream):
+            def __iter__(self):
+                yield b"body"
+
+        exc = httpx.HTTPStatusError(
+            "404",
+            request=httpx.Request("POST", "http://ocr.example/ocr/text"),
+            response=httpx.Response(404, stream=_Unread()),
+        )
+        err = _classify_status(exc, "monkey_1", "text")
+        assert isinstance(err, RequestRejectedError)
+        assert err.body_text == ""
+        assert str(err) == "monkey_1 OCR text HTTP 404"
+
     async def test_connect_error_transient(self):
         def handler(request):
             raise httpx.ConnectError("refused", request=request)
diff --git a/tests/unit/test_openai_compat.py b/tests/unit/test_openai_compat.py
index 5ac6bbd..2e2067c 100644
--- a/tests/unit/test_openai_compat.py
+++ b/tests/unit/test_openai_compat.py
@@ -16,6 +16,7 @@ from polygateway.errors import (
 )
 from polygateway.middleware.telemetry import TelemetryEmitter
 from polygateway.pricing import ModelPrice, PricingTable
+from polygateway.transports._http_errors import summarize_body
 from polygateway.transports.openai_compat import (
     OpenAICompatTransport,
     _iter_sse_deltas,
@@ -691,6 +692,125 @@ class TestErrorTranslation:
             await _complete(_transport_for(handler), _source())
 
 
+# issue #10 原文给出的真实响应体(一字不改): 关键在于 code 收尾
+_REJECT_BODY = (
+    '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+    'and cannot be opened","type":"invalid_request_error","param":"",'
+    '"code":"invalid_parameter_error"}}'
+)
+
+
+class TestErrorBodyRetention:
+    """issue #10: 网关说了什么必须活着离开翻译层——message 与字段各留一份。"""
+
+    @pytest.mark.parametrize(
+        ("status", "exc"),
+        [
+            (400, RequestRejectedError),
+            (401, SourceDeadError),
+            (403, SourceDeadError),
+            (404, RequestRejectedError),
+            (500, TransientError),
+            (503, TransientError),
+        ],
+    )
+    async def test_every_non_2xx_branch_keeps_the_body(self, status, exc):
+        def handler(request):
+            return httpx.Response(status, content=_REJECT_BODY.encode())
+
+        with pytest.raises(exc) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert ei.value.body_text == _REJECT_BODY
+        # message 与字段共用同一份串: 遥测里看到的与下游 catch 到的不得打架
+        assert str(ei.value).endswith(f" | {_REJECT_BODY}")
+        assert "invalid_parameter_error" in str(ei.value)
+
+    async def test_rate_limited_429_keeps_body_and_retry_after(self):
+        def handler(request):
+            return httpx.Response(
+                429,
+                content=b'{"error":{"message":"per-minute cap 3"}}',
+                headers={"retry-after": "2.5"},
+            )
+
+        with pytest.raises(TransientError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert "per-minute cap 3" in str(ei.value)
+        assert ei.value.retry_after_s == 2.5  # 摘要不得干扰既有解析
+
+    async def test_insufficient_quota_429_keeps_body(self):
+        body = json.dumps(
+            {"error": {"type": "insufficient_quota", "message": "daily budget spent"}}
+        )
+
+        def handler(request):
+            return httpx.Response(429, content=body.encode())
+
+        with pytest.raises(SourceDeadError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert "daily budget spent" in str(ei.value)
+
+    async def test_oversized_insufficient_quota_still_classified_dead(self):
+        """实现红线: 类型判定必须读**原文**。
+
+        摘要会破坏 JSON 结构,若改用摘要解析,超长 body 的配额耗尽将退化成普通
+        限速——配额已耗尽的源不再 force_open,一个诊断改进就变成了治理 bug。
+
+        **填充必须是多个键**,不能是单个超长字符串值: 后者的截断点落在字符串
+        *内部*,省略标记成了合法的字符串内容,而头尾保留又让尾部的 error 对象
+        幸存——摘要照样解析得出 `insufficient_quota`,用例即告空转(2026-08-16
+        verifier 变异测试发现: 按错误写法实现,全套件 824 项依然全绿)。多键
+        填充让截断点落在结构记号之间,摘要才真正不可解析。
+        """
+        body = json.dumps(
+            {**{f"k{i}": "v" * 10 for i in range(300)}, "error": {"type": "insufficient_quota"}}
+        )
+        assert len(body) > 2048
+        with pytest.raises(json.JSONDecodeError):
+            # 判别力的前提: 摘要确实不再是合法 JSON,读它必然拿不到 type
+            json.loads(summarize_body(body))
+
+        def handler(request):
+            return httpx.Response(429, content=body.encode())
+
+        with pytest.raises(SourceDeadError):
+            await _complete(_transport_for(handler), _source())
+
+    async def test_empty_body_leaves_no_dangling_separator(self):
+        def handler(request):
+            return httpx.Response(400, content=b"")
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert str(ei.value) == "qwen_1 请求被拒: 400"
+        assert ei.value.body_text == ""
+
+    @pytest.mark.parametrize("body", [b"<html>gateway down</html>", b"\xff\xfe not utf-8"])
+    async def test_non_json_and_non_utf8_bodies_do_not_explode(self, body):
+        def handler(request):
+            return httpx.Response(400, content=body)
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert ei.value.status_code == 400  # 分类不受 body 形态影响
+
+    async def test_non_stream_path_keeps_the_body(self):
+        def handler(request):
+            return httpx.Response(400, content=_REJECT_BODY.encode())
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source(), stream=False)
+        assert ei.value.body_text == _REJECT_BODY
+
+    async def test_embedding_path_keeps_the_body(self):
+        def handler(request):
+            return httpx.Response(400, content=_REJECT_BODY.encode())
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _transport_for(handler).embed(texts=["hi"], source=_source(), call_id="cid-embed")
+        assert ei.value.body_text == _REJECT_BODY
+
+
 class TestLifecycle:
     async def test_aclose_idempotent(self):
         def handler(request):