---
title: 响应信封与错误码
description: 所有对外 API 共用的响应信封结构与全量错误码速查。
icon: ListChecks
---

> 所有 PAC 对外 API(及宿主需实现的资源 endpoint / push 入口)**共用同一套响应信封与错误码**。本页是全局约定速查,与下方各 endpoint 的 OpenAPI 参考互补。真理源:`packages/types/src/schemas/wrap.ts`(`ApiCode`)。

---

## 响应信封

**HTTP 状态码恒为 `200`** —— `5xx` 只留给真崩溃(网关 / 服务挂),便于 LB / k8s 探针识别死实例。业务结果一律看信封里的 `code`。

```jsonc
// 成功
{ "code": 0, "msg": "ok", "data": { /* ... */ } }

// 失败
{ "code": 10002, "msg": "请求字段校验失败", "data": null,
  "details": [ /* 可选,结构化诊断,如哪个字段不过 */ ] }
```

| 字段 | 说明 |
|---|---|
| `code` | `0` = 成功;非 0 = 错误(见下表) |
| `msg` | 一句话给人看 |
| `data` | 成功负载;失败为 `null` |
| `details` | 可选,失败时的结构化诊断(数组) |

> 例外:SSE 流式端点与 `/health` 不套信封。

---

## 编码规则(5 位 `A-BB-CC`)

| 段 | 含义 |
|---|---|
| **A** | 来源:`0` 成功 / `1` 客户端错 / `2` 业务状态错 / `3` 上游(宿主 / AI / 数仓)/ `9` PAC 内部 |
| **BB** | 模块:`00` 通用 · `01` 鉴权 · `02` 平台 · `03` 患者 · `04` 画像 · `05` 计划 · `06` 执行 · `07` 事实 · `08` 同步 · `09` agent · `10` 租户 |
| **CC** | 模块内序号 |

---

## 错误码速查

### 1xxxx · 客户端错误

| code | 含义 |
|---|---|
| `0` | 成功 |
| `10001` | 请求格式错误 |
| `10002` | 请求字段校验失败(看 `details`) |
| `10003` | 请求过于频繁(限流) |
| `10004` | 资源不存在(通用) |
| `10101` | appId 或 appSecret 不正确 |
| `10102` | 一次性 code 无效或已过期 |
| `10103` | refresh token 无效 |
| `10104` | 未携带 access token |
| `10105` | access token 已过期 |
| `10106` | access token 解析失败 |
| `10107` | 权限不足 |
| `10201` | 宿主不存在 |
| `10202` | 宿主已存在 |
| `10301` | 患者不存在 |
| `10401` | 画像不存在 |
| `10501` | 计划不存在 |

### 2xxxx · 业务 / 状态错误

| code | 含义 |
|---|---|
| `20501` | 计划已被分配 |
| `20502` | 计划已完成,不能再修改 |
| `20503` | 计划联系次数超限,已熔断 |

### 3xxxx · 上游 / 第三方

| code | 含义 |
|---|---|
| `30801` | 宿主接口不可达 |
| `30802` | 宿主字段映射漂移 |
| `30803` | 宿主登录失败 / 凭据失效 |
| `30804` | 该平台不支持单患者即时刷新 |
| `30901` | AI 网关响应超时 |
| `30902` | AI 网关返回错误 |

### 9xxxx · PAC 内部

| code | 含义 |
|---|---|
| `90000` | 服务内部错误 |
| `90001` | 数据库错误 |
