# Error Handling

> How errors are handled in this project.

---

## Overview

<!--
Document your project's error handling conventions here.

Questions to answer:
- What error types do you define?
- How are errors propagated?
- How are errors logged?
- How are errors returned to clients?
-->

(To be filled by the team)

---

## Error Types

<!-- Custom error classes/types -->

(To be filled by the team)

---

## Error Handling Patterns

<!-- Try-catch patterns, error propagation -->

### 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

<!-- Standard error response format -->

(To be filled by the team)

---

## Common Mistakes

<!-- Error handling mistakes your team has made -->

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