错误码一览

所有接口在出错时返回统一的错误格式和语义明确的错误码，方便调用方精确定位问题并采取相应处理措施。

错误响应格式

{
  "success": false,
  "code": "USER_NOT_FOUND",     // 业务错误码（字符串）
  "message": "用户不存在",        // 人类可读描述
  "timestamp": "2026-04-01T10:00:00+08:00"
}

参数校验失败时（422），响应额外包含 errors 字段，列出每个字段的具体错误信息：

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "请求参数不合法",
  "errors": {
    "user.name": ["姓名不能为空"],
    "user.birth_date": ["出生日期格式不正确，应为 Y-m-d"]
  },
  "timestamp": "..."
}

HTTP 状态码

状态码	含义	常见场景
200	成功	GET 查询、PATCH 更新
201	创建成功	POST 创建资源
400	请求格式错误	JSON 格式非法、Content-Type 错误
401	鉴权失败	签名错误、时间戳过期、App-Id 不存在
403	无权限	应用未开通对应 Scope
404	资源不存在	open_user_id / member_id 不存在或不属于当前应用
422	参数校验失败	必填字段缺失、字段格式不合法
429	超出限流	请求频率超过应用配额
500	平台内部错误	服务异常，可稍后重试

S2S 接口错误码

鉴权类错误

code	HTTP	说明	处理建议
`HTTP_401`	401	签名校验失败或 App-Id 不存在	检查 AppKey / AppSecret 及签名算法
`HTTP_401`	401	时间戳超出 ±5 分钟窗口	检查服务器时钟，使用最新时间戳
`HTTP_429`	429	请求频率超过应用限制（默认 60 次/分钟）	降低频率，实现指数退避重试

用户互通错误

code	HTTP	说明	处理建议
`USER_NOT_FOUND`	404	open_user_id 不存在或不属于当前应用	确认 open_user_id 是否为本应用注册返回的值
`FAMILY_GROUP_NOT_FOUND`	404	家庭组不存在、已解散或无权操作	确认 groupId / app_group_id 是否正确
`FAMILY_MEMBER_NOT_FOUND`	404	家庭成员不存在或已删除	确认 memberId 是否正确
`INVALID_APP_GROUP_ID`	422	一步注册时 family_members 引用了不在本次 family_groups 列表中的 app_group_id	确保 family_members[].app_group_id 均存在于本次 family_groups
`VALIDATION_ERROR`	422	请求体字段格式不合法	查看响应 errors 字段中的具体字段名和错误描述

健康站错误

code	HTTP	说明	处理建议
`STATION_NOT_FOUND`	404	健康站不存在或已停用	重新查询附近健康站列表
`APPOINTMENT_CONFLICT`	409	用户已有进行中的预约	引导用户取消旧预约后重新预约
`SLOT_UNAVAILABLE`	410	预约时段已满或不可用	重新获取可用时段列表
`CHECKIN_CODE_INVALID`	422	到站核验码无效或已使用	引导用户在 App 内刷新生成新核验码
`BENEFIT_CARD_EXHAUSTED`	422	权益卡已无可用次数	引导用户续费或选择其他支付方式

参数校验错误

当请求体字段不符合要求时，接口返回 422 和 VALIDATION_ERROR 错误码，并在 errors 字段中详细列出每个字段的问题：

// 示例：注册绑定时缺少必填字段
{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "请求参数不合法",
  "errors": {
    "user.name": ["姓名 不能为空"],
    "family_members.0.relationship": ["家庭关系 不能为空"]
  },
  "timestamp": "..."
}

字段路径使用点号分隔，数组元素用数字下标表示（如 family_members.0.name）。

重试策略建议

HTTP 状态	是否建议重试	建议策略
4xx（除 429）	否	修复请求参数或凭证后重新发送
429	是	指数退避：1s → 2s → 4s → 8s，最多重试 5 次
500	是	等待 3 秒后重试，最多重试 3 次；持续失败则告警
超时/网络错误	是	指数退避重试，幂等接口（GET / 注册绑定）安全可重试

注册绑定接口（POST /open/v1/channel/users）为幂等设计，重复调用不产生重复数据，可安全重试。 DELETE 操作不幂等，重试前先 GET 确认资源状态。

健康站接口 Changelog