Skip to content

docs: 错误码表补上「采纳上游 error.statusCode」的语义（#43 文档补充） #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Catapult291 wants to merge 1 commit into from
Closed

docs: 错误码表补上「采纳上游 error.statusCode」的语义（#43 文档补充） #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 4 additions & 2 deletions README_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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。

## 模型列表

Expand Down