---
url: /docs/api-docs/v1/ranking/error-codes.md
---
# ranking —— 错误码矩阵（40422xxx）

> 完整 action 字段表见 [ranking 概览](/api-docs/v1/ranking/)。
> 错误码权威注册：`docs/ai-contexts/error-code-registry.md`。
> HTTP 状态映射：`src/app/ranking/domain/exceptions.py::cz_ranking_error_to_http_status`。

## 错误码全表（3 个）

| code | 名称 | HTTP | 触发场景 |
|---|---|---|---|
| `40422001` | `PARAM_INVALID` | **400** | groupRankingMulti: sportType/period 越界 · rawFoodRanking: scope 越界 / scope=city 缺 cityAdcode / cityAdcode 非 6 位 |
| `40422002` | `UNAUTHORIZED` | **401** | 未登录 / token 无效 |
| `40422004` | `NOT_FOUND` | **404** | rawFoodRanking: **UseCase 未装配**（工厂 `ranking_use_cases.get("rawFoodRanking")` 返回 None） |

## 复用段说明

40422xxx 段在 ranking 模块与 stats 模块**事实共享**（注册表在案），是历史复用而非新开段。

### 各 action 错误码速查

| action | 可触发的码 |
|---|---|
| `groupRankingMulti` | `40422001` · `40422002` |
| `rawFoodRanking` | `40422001` · `40422002` · `40422004`（仅 rawFoodRanking 未装配时） |

## 关键设计点

### 40422004 用途

为 rawFoodRanking **未装配**场景预留 —— 工厂方法 `create_ranking_usecases` 若未注入 `raw_food_catalog` 参数，则 use cases dict 中没有 `rawFoodRanking` 键，dispatch 走默认 raise `RankingError(NOT_FOUND, "rawFoodRanking 未装配")`。

dev/mock 默认装配真 catalog；生产环境若漏装配（或 feature flag 关）会返这条。前端拿到 → 「功能暂未开放」提示即可。

### HTTP 状态码设计

| 类别 | HTTP | 错误码 |
|---|---|---|
| 参数校验 | 400 | `40422001` |
| 未登录 | 401 | `40422002` |
| 资源/能力不存在 | 404 | `40422004` |

## 错误码段治理

* **段位**：`40422xxx`（ranking 与 stats 共享）
* **本段已用**：3 个（`001` / `002` / `004` —— `003` 因与历史冲突跳过）
* **预留**：5~999
* **守卫**：`scripts/check_error_code_segments.py`
* **注册表**：`docs/ai-contexts/error-code-registry.md`

## v1 实测（来自 test\_raw\_food\_ranking.py）

```text
40422001 → scope="galaxy"（越界）/ scope="city" 缺 cityAdcode / cityAdcode="12345"（非 6 位）
40422002 → 无 Bearer token
40422004 → rawFoodRanking UseCase 为 None（构造空 dict 触发）
```

后端 5 例全绿，回归 `tests/integration/test_raw_food_ranking.py`（15 例）。