From 24cbd0b7304a537b0b1790242cc08ced7e965503 Mon Sep 17 00:00:00 2001
From: Catapult291 <200960228+Catapult291@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:47:25 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=94=99=E8=AF=AF=E7=A0=81=E8=A1=A8?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5=E3=80=8C=E9=87=87=E7=BA=B3=E4=B8=8A=E6=B8=B8?=
 =?UTF-8?q?=20error.statusCode=E3=80=8D=E5=90=8E=E7=9A=84=E8=AF=AD?=
 =?UTF-8?q?=E4=B9=89=EF=BC=88#43=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#43 让 mapCcEventError 采纳 error 事件自带的 statusCode 之后，README / README_zh
的错误码表没跟上：仍写着「400 = 请求格式错误」、「502 = CC 上游错误」，
看不出上游声明的状态码现在会原样透出。

- 400 行补上「或上游 error 事件自带 statusCode: 400（如内容风控拒绝）」
- 502 行收窄为「事件未声明状态码，或声明的状态码不在映射表内」
- 两表下各补一段说明：CC 把失败放在响应流里上报
  （{"type":"error","error":{...,"statusCode":N,"isRetryable":B}}），代理取值
  顺序是 `<NNN>` 前缀优先、其次 statusCode（与 CLI 的 readStreamErrorEvent 一致），
  映射方式与 HTTP 层错误相同（声明的 402 仍落 429）。

只改文档，无代码行为变更。
---
 README.md    | 6 ++++--
 README_zh.md | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b24f842..c5097c5 100644
--- a/README.md
+++ b/README.md
@@ -261,10 +261,12 @@ Health check. Returns `OK`.
 
 | HTTP Status | Description |
 |-------------|-------------|
-| 400 | Invalid request format |
+| 400 | Invalid request format, or an upstream error event declaring `statusCode: 400` (e.g. a content rejection) |
 | 401 | API Key missing / invalid format / rejected (Key must start with `user_`; sent via `Authorization: Bearer` or `x-api-key`) |
 | 429 | Zero output tokens, or idle timeout (30s streaming / 90s non-streaming) — SDK auto-retry with `Retry-After`; after 3 consecutive timeouts a "reduce context" hint is returned |
-| 502 | CC upstream error |
+| 502 | CC upstream error — the event declares no status, or one with no mapped equivalent |
+
+CC reports failures inside the response stream rather than as an HTTP status: `{"type":"error","error":{...,"statusCode":N,"isRetryable":B}}`. The proxy takes that status (a leading `<NNN>` in the message wins over it, matching the CLI) and maps it the same way as an HTTP-level error — a declared 402 still surfaces as 429 — so an upstream-declared 400 or 429 reaches the client with its own status instead of a blanket 502.
 
 ## Model List
 
diff --git a/README_zh.md b/README_zh.md
index 0e3ec95..a8ff41f 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -259,10 +259,12 @@ data: {"type":"message_stop"}
 
 | HTTP 状态 | 说明 |
 |-----------|------|
-| 400 | 请求格式错误 |
+| 400 | 请求格式错误，或上游 error 事件自带 `statusCode: 400`（如内容风控拒绝） |
 | 401 | API Key 缺失/格式不对/无效（Key 必须以 `user_` 开头；通过 `Authorization: Bearer` 或 `x-api-key` 传入） |
 | 429 | 零输出 token，或流空闲超时（30s 流式 / 90s 非流式）——带 `Retry-After`，SDK 自动重试；连续 3 次超时返回"压缩上下文"提示 |
-| 502 | CC 上游错误 |
+| 502 | CC 上游错误——事件未声明状态码，或声明的状态码不在映射表内 |
+
+CC 把失败放在响应流里上报，而不是用 HTTP 状态：`{"type":"error","error":{...,"statusCode":N,"isRetryable":B}}`。代理会取这个状态（消息里的 `<NNN>` 前缀优先，与 CLI 一致），按与 HTTP 层错误相同的方式映射（声明的 402 仍落 429），所以上游声明的 400 / 429 会带着自己的状态到达客户端，而不是一律 502。
 
 ## 模型列表