跳转到主要内容
1签 (OneSign)

接入常见问题

本页内容

按照连接、认证、权限、业务状态的顺序排查。保留 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 接口参考。

权限与应用范围

请求可以到达平台,但返回 403、404 或空列表时,先用同一凭据查询当前身份,确认账号、动作与资源范围,再按现象定位。

看到的现象下一步
应用列表为空确认账号下有对应产品的应用。普通分发显式传 module=distribution,企业签名传 enterprise;再核对这些应用是否被当前 API 应用授权或排除。
应用、版本或任务返回 404从自己的列表或原成功回执取得完整 ID,核对资源是否仍存在,以及版本、上传任务和签名任务是否属于路径中的应用。首次预留的新应用使用创建状态接口,安装包保存后再查询正式应用。
网站能操作,API 却返回 403网站权限与 API 授权分别校验。核对账号功能许可、API 应用动作、目标资源与程序实际出口 IP;列表读取、修改、下载和付款各自授权。
浏览器提示 CORS使用已批准 public 客户端的精确 Origin,并核对 OAuth、方法和请求头。文件传输失败时保留上传任务 ID 和 request_id,联系平台核查传输服务;无需自行设置平台存储配置。需要长期 Secret 的业务放在自己的后端。
BudgetDisabled 或预算不足核对账号与当前 API 应用两层预算。余额、财务读取与付款分别授权,余额充足也可能因预算未启用或额度不足被拒绝。

完整授权条件见访问权限与资源 ID。需要更换凭据时按密钥轮换步骤执行,并核对原有临时凭据或用户授权的影响。

写入超时后恢复

没有收到响应时,原请求可能已被处理。先恢复保存的应用、任务、报价或订单记录,再决定查询或重试。同一次管理写入保留原幂等键、路径和正文。

失败步骤恢复方法
上传中断查询原上传任务。分片先核对已确认内容,使用原文件、原摘要和检查点补齐;存储传输完成后仍需提交平台校验。网站通知中的上传 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 无需提供。