接入 FAQ 与错误排查

本页汇总开放平台接入阶段最常见的问题类型、错误码含义和推荐排查路径。

如联调中出现请求失败、返回异常、权限受限或结果不符合预期，可优先从本页定位问题，再回到对应接口页核对参数与业务口径。

适用范围

本页适用于当前公开开放的 2.0 API 文档，重点覆盖以下场景：

• 首次联调时无法跑通最小调用样例
• 已发起请求但返回鉴权、签名、权限或参数类错误
• 调用量、频率、余额或授权期相关错误
• 返回结构正常，但结果为空、找不到数据或与业务预期不一致

建议排查顺序

接入阶段建议按下面的顺序排查，而不是一开始就只盯着业务参数：

1. 先确认调用地址、协议和版本路径是否正确
2. 再确认 appid、sign、timestamp 是否完整且有效
3. 再确认接口权限、调用来源、授权期和配额状态
4. 最后核对业务参数、字段口径和数据是否真实存在

常见问题

1. 请求为什么直接失败或无法访问

优先检查以下几项：

• 是否使用 HTTPS
• 主路径是否为 https://medical.nocode.com/open/
• 接口路径是否带了正确的 2.0 版本前缀，即 /v2/
• 是否误把文档页地址当成了接口地址

建议先用一个参数最少的基础查询接口做验证，确认网络、签名和权限链路都正常，再继续联调复杂接口。

2. 为什么会出现 400101 签名错误

400101 通常意味着签名算法、参与签名的原始值或拼接顺序有问题。

建议重点检查：

• 是否严格使用 lowercase(MD5(appid + token + timestamp))
• appid、token、timestamp 是否与实际发送值完全一致
• 是否多拼了空格、换行或额外分隔符
• timestamp 是否先转成了秒级，而不是毫秒级
• 签名结果是否已经转成小写

如果多个接口都报同样问题，通常不是接口文档问题，而是签名封装逻辑需要统一修正。

3. 为什么会出现时间戳相关错误

常见时间戳错误包括：

• 400102：时间戳过期
• 400103：未提供时间戳
• 400105：时间戳格式无效

建议重点确认：

• timestamp 是否为毫秒级 Unix 时间戳
• 调用服务器时间是否与标准时间偏差过大
• Header 是否真的把 timestamp 发出去了，而不是只在本地变量中生成

如果出现偶发性时间戳错误，通常需要检查服务端时钟同步，而不是单纯重试。

4. 为什么会出现权限或授权类错误

权限类错误通常包括：

• 400110：当前无接口调用权限
• 400114：调用来源校验未通过
• 400116：授权未生效或已过期

这类错误优先排查开通状态，而不是继续修改业务参数。

建议确认：

• 当前 appid 是否已经开通目标接口
• 是否使用了约定的调用来源或出口环境
• 授权是否仍在有效期内
• 当前调用的接口是否属于已开通能力范围

5. 为什么会出现参数错误或查不到数据

这类问题常见于：

• 400108：请求参数有误
• 400111：未找到对应数据

建议分两层检查：

第一层：检查技术格式

• 参数名是否与接口文档完全一致
• 类型是否正确，例如字符串、分页值、布尔值
• POST 请求是否使用了正确的 Content-Type
• 必填字段是否缺失

第二层：检查业务口径

• 传入 ID 是否属于当前能力域，例如 drug_package_id、hospital_id
• 输入关键词、地区、条形码或任务 ID 是否真实存在
• 是否混用了不同接口体系下的标识符

6. 为什么会出现配额、频率或余额相关错误

这类错误通常包括：

• 400112：已超过当日调用上限
• 400113：请求过于频繁，请稍后再试
• 400115：账户余额不足

建议优先确认以下事项：

• 当前日调用量是否已达到上限
• 单位时间内是否存在突发并发或重复重试
• 是否已经接入了重试退避机制
• 当前合作范围是否有余额或套餐限制

如果问题出现在批量任务或重试逻辑中，建议先检查本地限流和幂等策略，再确认平台侧额度。

7. 返回结构正常，但结果和预期不一致，应该怎么查

这类问题不一定是接口异常，也可能是业务理解差异。

建议按下面顺序核对：

1. 接口是否选对，例如查询接口、对码接口和结果查询接口是否混用
2. 是否理解了字段语义，例如标准 ID、状态字段、推荐结果和辅助信息的边界
3. 是否把智能接口结果当成确定性结论使用
4. 是否需要结合详情接口、结果查询接口或能力说明页一起理解

对于智能分诊、智能问病、推荐用药等接口，结果默认应理解为「辅助判断」或「候选参考」，不应当作正式诊断结论。

8. 遇到 400109 系统异常应该怎么处理

400109 通常代表平台内部错误或暂时性异常。

建议处理方式：

• 保留 X-Request-ID 或本地请求流水
• 记录请求时间、接口名称、核心参数和返回结果
• 避免无节制高频重试
• 先确认是否为偶发问题，再决定是否升级排查

如果同一接口、同一参数持续稳定返回 400109，通常需要结合请求链路和时间点做进一步定位。

常见错误码速查表

常见错误码已独立整理为 错误码速查表。

如需快速查阅错误码英文解释和对应中文，可直接进入该页面；如需继续排查处理路径，可回到本页结合上下文说明继续定位。

联调阶段建议保留哪些信息

为了便于复盘和快速定位问题，建议在本地系统至少保留：

• 请求时间
• 请求接口名称
• appid
• timestamp
• X-Request-ID
• 核心业务参数
• 平台返回的错误码和错误信息

如涉及批量任务、对码结果查询或异步回调，还建议额外保留：

• task_id
• 原始业务记录 ID
• 任务状态流转记录
• 回写结果和人工复核记录

建议继续阅读

• 需要完整理解接入顺序：阅读 快速开始与接入流程
• 需要核对签名、Header 和协议约定：阅读 认证与调用约定
• 需要直接看请求样例：阅读 请求示例与调试
• 需要理解权限、配额和上线规则：阅读 平台规则总览