接入常见问题
本页内容
按照连接、认证、权限、业务状态的顺序排查。保留 HTTP 状态、错误码、请求 ID 和相关资源 ID,有助于快速定位问题。
连接与签名
先确定失败发生在加载 SDK、请求平台,还是传输安装包。记录当前步骤与 HTTP 状态,再按下面的顺序排查。
| 看到的现象 | 下一步 |
|---|---|
| SDK 或模块无法导入 | 按对应语言指南核对运行版本、解压目录和入口。Go 保留 go.mod,Java 保留源码参数文件,Rust 保留 Cargo.lock;Python 标准库脚本与 SDK 使用各自的导入方式。 |
连不上或 TransportError | 从程序所在网络检查 DNS、TLS、代理和实际出口。业务 API 使用网站 HTTPS 主域名;安装包传输使用上传凭证中的存储地址。 |
HTTP 401 / InvalidCredentials | 核对同一组 ID 与 Secret、有效期和时钟。使用 SDK 时确认配置已重新加载;自行签名时逐项核对主机、路径、查询编码和实际正文。OAuth 不混用 AccessKey 签名头。 |
HTTP 401 / RequestExpired | 校准程序运行环境的 UTC 时钟,签名使用当前时间,允许偏差最多 300 秒。Unix 秒与毫秒分别转换,不把缓存的日期与 nonce 用于下一次请求。 |
返回 HTML 或 InvalidResponse | 先看实际 HTTP 状态、访问域名与代理错误。确认请求到达平台 JSON 入口;HTML、空响应和浏览器登录页不能作为成功业务结果解析。 |
公共格式和认证头见请求与响应约定。OAuth 令牌端点使用自己的表单与错误格式,详见OAuth 接口参考。
写入超时后恢复
没有收到响应时,原请求可能已被处理。先恢复保存的应用、任务、报价或订单记录,再决定查询或重试。同一次管理写入保留原幂等键、路径和正文。
| 失败步骤 | 恢复方法 |
|---|---|
| 上传中断 | 查询原上传任务。分片先核对已确认内容,使用原文件、原摘要和检查点补齐;存储传输完成后仍需提交平台校验。网站通知中的上传 ID 不能用来恢复 API 上传任务。 |
| 上传进度 100%,仍拿不到版本 | 继续查询原上传任务,等待 state=succeeded 且取得版本 ID。validating 表示仍在校验,failed 或 cancelled 需按返回说明处理。 |
| 签名提交或等待超时 | 查询原签名任务与准确产物。terminal=true 后仍需检查 status=succeeded;被替代、失败或取消均不是成功。等待超时不会自动取消服务器任务。 |
| 付款、密钥开通或扩容响应丢失 | 查询原报价、核销回执或订单。未拿到回执 ID 时按原请求和原幂等键恢复,不另建相同业务。开通到账后如需签名,再明确提交签名任务。 |
| 退款响应丢失 | 查询原订单退款状态和回执,核对到账与权益撤销结果。资格或账务错误先解决原因,不重复调整金额或提交另一笔退款。 |
RevisionConflict | 重新读取最新 revision 或当前版本,向使用者确认差异后开展新的修改,不覆盖其他已保存内容。 |
OAuth 授权码与刷新令牌为一次性使用,不套用上述业务 API 的幂等重放方式。刷新结果丢失时按令牌恢复说明处理。下载凭证或临时密钥的幂等重放可能不再交付 URL、Secret,先检查回执再决定是否新申请。
其他错误的处理方式见错误处理、幂等与重试。
提供排查信息
排查仍未解决时,整理下表信息,帮助定位同一次调用。不要把整组配置或完整响应直接粘贴到日志与工单。
| 提供的信息 | 如何取得 |
|---|---|
| 失败时间与时区 | 记录实际发生时间、程序运行环境和所用 SDK 版本,便于区分旧请求与本次重试。 |
| 接口与结果 | 记录方法、操作名、HTTP 状态、错误码与 request_id。只有网络错误时,说明未取得平台请求标识。 |
| 相关资源 | 提供本人应用 ID、已有上传或签名任务 ID、报价或订单 ID;说明在哪一步首次失败。 |
| 上传问题 | 补充文件大小、整包或分片方式、失败进度及是否使用原文件恢复。说明失败发生在平台 API 还是存储传输。 |
隐藏 AccessKey Secret、OAuth 令牌、授权码、verifier、开通密钥、完整短期 URL 和原始设备导出内容。应用 ID 与 request_id 可以用于定位,密码与 Secret 无需提供。