返回 HTML、404 或重定向
请求没有进入预期 JSON 业务链。确认使用文档展示的完整地址、HTTPS 和 POST；Connect 地址末尾不要由客户端自行追加斜杠。
核对接入方式 →外观
错误与请求 ID
不要只看 HTTP 200，也不要看到失败就反复重试。先判断故障发生在网络、接入配置、业务数据还是平台内部。
1. 看响应状态码、Content-Type、业务字段
2. 查配置项目、接口、协议和配额
3. 定位置客户端修复或平台处理
4. 留证据请求 ID、时间和脱敏参数
先按响应类型判断
| 表现 | 所在层 | 先做什么 |
|---|---|---|
| HTML、404、301 或 302 | 地址或 Web 路由 | 核对完整 HTTPS 地址、POST 方法和反向代理 |
| JSON，提示程序或接口不可用 | 平台配置 | 检查项目状态、验证开关和接口开通 |
| JSON，提示签名、时间戳或 nonce 错误 | 客户端接入 | 对照协议重新计算，不要盲目修改平台密钥 |
| JSON，提示卡密、设备或有效期问题 | 正常业务拒绝 | 在卡密管理中核对数据，不做系统重试 |
| JSON，带请求 ID 或错误 ID | 平台诊断 | 保存 ID，到运行健康或工单中继续处理 |
接入与平台配置
提示“程序不存在”
通常是程序 ID 错误、字段放错位置或传输模式与接口不一致。标准 HTTP 使用 app，Connect 把程序 ID 放在 URL。
提示“接口未开通”或“功能不可用”
先确认选择的是当前项目，再查看接口中心显示的开放策略和项目级开关。标准 HTTP 与 SDK 共用授权；Connect 是独立协议，但不一定需要用户手动开通。
打开接口中心项目停用或验证关闭
程序运行状态和验证开关是两层门禁。进入项目列表确认状态，再到该项目配置页开启验证。
打开项目列表签名、时间戳与 nonce
签名错误
核对 V1/V3 协议、程序 ID、签名密钥、规范串和最终发送的原始 BODY。V3 不使用 V1 的 t、s 表单签名。
时间戳超出窗口
使用 10 位秒级 Unix 时间戳，客户端系统时间应自动同步。不要发送 13 位毫秒时间戳或格式化日期。
查看时间窗说明 →nonce 重复
每次请求生成全新的随机串。网络重试也必须重新生成 nonce、时间戳和签名，不能原包无限重放。
查看防重放策略 →不要为通过验证而关闭安全策略
签名失败时先修复客户端规范串。直接关闭签名、放宽时间窗或长期复用密钥只能掩盖问题，并会降低当前项目的请求安全性。
卡密、设备与会话
卡密无效、封禁、过期或次数耗尽
这些是可预期业务结果。检查卡密是否属于当前项目、状态和到期时间是否正确，不要生成平台故障工单。
打开卡密管理设备不匹配或设备位已满
确认设备码在重启后保持稳定。需要换设备时走公开解绑或后台清空绑定，不要随机更换设备码绕过限制。
检查卡密绑定登录成功后心跳失效
检查保存的是否为 SDK session_token，并确认心跳间隔、最近心跳和项目全体下线状态。
请求 ID 与平台故障
完整请求进入平台后，如果发生需要追踪的接入安全问题或平台异常，响应可能包含 request_id 或 error_id。
- 卡密无效、过期、封禁、密码错误等业务结果不会升级为平台故障。
- 签名、时间戳、重放等问题属于接入安全诊断，应先按本页修复配置或客户端。
- 项目不可用、运行异常或内部处理失败可能生成错误 ID，并按项目归属推送给作者、管理员和有权限的客服。
提交工单时提供：发生时间、接口名称、程序 ID、客户端版本、request_id / error_id、脱敏请求字段和可复现步骤。不要提交完整卡密、签名密钥、Token 或用户隐私。
仍然无法解决
- 用同一程序 ID 和专用测试卡重新发起一次请求，记录准确时间。
- 对照选择接入方式确认没有混用标准 HTTP 与 Connect 字段。
- 在运行健康查看项目状态；有请求 ID 时再提交工单。
- 工单描述实际结果和预期结果，不要只写“接口不能用”。