cc-web/.trellis/spec/backend/error-handling.md

Error Handling

How errors are handled in this project.

---

Overview

(To be filled by the team)

---

Error Types

(To be filled by the team)

---

Error Handling Patterns

Codex App 过程错误与终态错误

• app-server 的 JSON-RPC 方法名为 error 时，不能仅凭方法名判定当前 turn 已结束；必须结合消息语义和后续终态事件处理。
• 纯 Reconnecting... N/M 表示 provider 内部重连进度：应向客户端展示，但不得写入最终错误、清理 active turn 或启动新的 cc-web 业务重试。
• 503 Service Unavailable、No available providers、service_unavailable_error 等终态错误必须保留完整错误信息，再交给服务端重试分类。
• 自动续接必须携带并校验原 expectedThreadId；恢复到不同 thread 时应停止，不能用新 thread 掩盖上下文丢失。

---

API Error Responses

(To be filled by the team)

---

Common Mistakes

• 把每个 app-server error 通知都返回为 done: true，会在 provider 自身仍重连时提前关闭 turn，并与 cc-web 重试状态机形成交错重试。
• 使用非锚定正则识别 Reconnecting... N/M，可能误吞同时包含最终 503 的组合错误；过程通知识别应匹配整条消息。