---
description: Mobile and eval-web API client error handling and auth refresh
globs: app-expo/src/**/*.{ts,tsx},app-eval-web/src/**/*.{ts,tsx}
alwaysApply: false
---

# API Client（app-expo / app-eval-web）

后端错误体为 `{ error_code, message, request_id }`（旧版可能仍有 `{ detail }`）。

## 错误解析
- **统一使用 `parseApiError`**（`app-expo/src/core/api/parseApiError.ts`、`app-eval-web/src/parseApiError.ts`）
- 展示给用户 / toast 用返回的 `message`；分支逻辑用 `errorCode`（对应后端 `error_code`）
- **禁止**在新代码里直接读 `body.detail` 或假设 FastAPI 默认错误形状

## Token 刷新
- `app-expo` 并发 401 refresh 必须走 `refresh-lock.ts`，避免双端同时 refresh 触发 `REFRESH_TOKEN_REUSE`
- refresh 失败应清 session 并引导重新登录，不要无限重试同一 refresh token

## 类型
- 共享错误 body 形状见各 app 的 `ApiErrorBody` / `types.ts`；与 OpenAPI `ErrorResponse` 对齐