---
title: 接入 FAQ 与错误排查
description: 汇总鉴权、签名、权限、限流和常见错误码的排查建议。
sidebar_position: 1
---


# 接入 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`，通常需要结合请求链路和时间点做进一步定位。

## 常见错误码速查表

常见错误码已独立整理为 [错误码速查表](/doc/faq/error-code-quick-reference)。

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

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

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

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

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

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

## 建议继续阅读

- 需要完整理解接入顺序：阅读 [快速开始与接入流程](/doc/getting-started/quick-start-and-integration-flow)
- 需要核对签名、Header 和协议约定：阅读 [认证与调用约定](/doc/getting-started/authentication-and-calling-conventions)
- 需要直接看请求样例：阅读 [请求示例与调试](/doc/getting-started/request-examples-and-debugging)
- 需要理解权限、配额和上线规则：阅读 [平台规则总览](/doc/platform-rules/platform-rules-overview)