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

错误处理、幂等与重试

本页内容

先区分请求失败和业务任务失败,再决定查询、等待或重试。写入响应丢失时,原操作可能已经成功,应先核对结果并保持原幂等键。

读取成功与错误响应

成功响应从 data 读取结果,并保存 request_id。请求失败时按 error.code 做程序判断,message 用于给人阅读。异步任务还要检查业务状态,不能只看 HTTP 200。

错误响应示例
{
    "request_id": "11111111111111111111111111111111",
    "error": {
        "code": "Throttled",
        "message": "请求过于频繁,请稍后重试"
    }
}

无法解析的 HTML 可能来自代理或网关,不是平台 JSON 业务结果。排查时记录状态、错误码、请求 ID 和时间,不记录完整凭证或设备数据。

决定下一步

情况建议处理
400 请求格式或参数不正确核对方法、编码、字段类型与必填项,修改后再提交。
401 认证失败检查凭据、签名时间、域名和实际发送内容。
403 / 404核对当前账号、权限与应用归属,不通过递增 ID 试探其他资源。
405 方法不支持按接口指定的 GET 或 POST 发送请求。
409 版本、幂等或业务条件冲突按错误码分别处理。RevisionConflict 需重新读取和确认修改;IdempotencyConflict 需恢复原请求;报价过期或单位变化需重新核对并确认业务。
413 请求正文过大管理 JSON 正文控制在 16 KiB 内;安装包应按上传凭证传到存储服务。
422 当前业务无法执行按错误码核对余额、包状态或退款资格。先解决业务原因,不原样连续重试。
429 限流按 Retry-After 等待,限制重试次数和总时长。
网络超时或 5xx只读查询可有限重试;写入先确认原操作是否已受理或完成。

保存幂等键并重试

  1. 开始一次独立写操作时生成 16–64 位幂等键,并在首次请求前持久保存操作路径和正文。
  2. 重试时保持同一键、同一路径和相同正文,重新生成认证时间、nonce 与签名。
  3. 已保存资源 ID 时先查询原上传、任务、报价或订单。确需开展另一项业务时再使用新键。

幂等键不是可以无限期重建结果的凭证。各业务的恢复期限和回执规则不同,应遵循对应接口说明。签名工具对没有任务 ID 的提交恢复另有时间限制;财务操作优先按持久回执对账。

临时凭据、下载凭证和设备导出在重放时可能只返回回执,不再交付 Secret、URL 或导出内容。先检查响应,再明确决定是否需要发起新申请。

日期、金额、空值与两种认证请求头的区别,见请求与响应约定。异步任务失败与 HTTP 请求失败需要分开处理。

按问题查询错误码

先按错误码确定失败原因,再决定查询原结果、修改请求或稍后重试。下表列出业务 API 的错误;OAuth 见授权错误,Webhook 接收失败见通知排查。

共 87 个错误码

请求格式与并发冲突

HTTP错误码处理说明
400InvalidHost使用站点配置的 HTTPS 主域名,并用同一域名构造签名。
400InvalidRequest检查 GET 是否带正文,以及 POST 的 Content-Type 和幂等键。
413RequestTooLarge将管理 JSON 正文控制在 16 KiB 内。安装包文件应按上传凭证传到存储服务。
400HttpsRequired使用 HTTPS 网站主域名调用 API,并检查代理是否正确传递连接协议。
405MethodNotAllowed使用接口指定的 GET 或 POST 方法,不用方法覆盖请求头替代。
400InvalidQuery检查参数名称、格式、范围和 URI 编码,删除重复参数。
400InvalidInput按请求体字段表核对类型、枚举与必填项,排除未知或重复字段。
400InvalidCursor原游标已失效或与当前资源不匹配。保持筛选条件,从第一页重新查询。
409IdempotencyConflict同一个幂等键用于不同请求。恢复原请求的正文与路径。独立的新业务操作使用新键。
409RevisionConflict目标已被更新。重新读取当前版本或 revision,确认差异后再提交新的操作。

认证、授权与临时凭据

HTTP错误码处理说明
401InvalidCredentials凭据无效、已停用,或请求签名不匹配。核对 AK、环境、正文摘要和签名头。
401RequestExpired签名时间超出允许窗口。校准 UTC 时钟,生成新的日期、nonce 和签名。
409ReplayDetectednonce 已使用。保留原业务幂等键,使用新的 nonce 签名。
403AccessDenied检查当前身份的动作、资源范围、来源 IP 及功能准入。
404NotFound核对路径中各标识是否完整、属于同一业务应用且在当前授权范围内。
403CorsDenied浏览器须使用已批准 Origin 的 OAuth 客户端。核对来源、方法和请求头,不在浏览器使用长期 Secret。
403SessionsDisabled账号尚未允许签发只读临时凭据。检查开发者中心的会话设置。
400 / 403InvalidPolicy核对申请的动作、应用、网络、时长和限额是否在父凭据授权范围内。
409ParentExpiring父密钥剩余有效期不足。缩短申请时长或使用有效父密钥。
429SessionLimit有效临时会话已满。撤销不用的会话或等待过期。
409CredentialExpiring父凭据剩余有效期不足。换用有效凭据再申请下载链接。

应用、发布与下载

HTTP错误码处理说明
429CreationLimit待完成的应用预留过多。先完成现有预留,或等待过期释放。
403ManagementDisabled账号尚未开放应用管理。到开发者中心查看应用管理准入。
400ConfirmationRequired删除确认值有误。显示目标应用并确认,传入与路径相同的完整应用 ID。
409ApplicationConflict当前应用状态不允许该变更。重新读取资料或当前发布版本。
409ApplicationUnavailable应用状态已变化或当前不可操作。先核对应用详情和权益。
409CreationConflict应用预留已过期、已完成或已有上传任务。先查询应用创建状态与原上传任务,再决定是否重新创建应用预留。
422RollbackUnsupported目标历史签名包不满足回滚条件。核对证书、设备校验和版本状态。
403DownloadsDisabled该账号或包类型尚未开放下载凭证。核对原包和签名包的独立授权。
422PackageUnavailable指定版本没有请求的可用产物。重新检查版本和包类型。
403SettingsDisabled账号尚未开放分发设置修改,需单独取得准入。
503SettingsUnavailable分发设置暂不可用。保留原 revision,稍后重新读取并核对,不假定保存已成功。

上传与存储

HTTP错误码处理说明
422StorageUnsupported当前请求的文件传输方式不可用。上传请使用 SDK 上传助手或通用分片流程,无需选择存储厂商;下载请保留 request_id 联系平台。
422StorageUnverified文件传输服务暂不可用。保留原上传任务 ID 和 request_id 联系平台,不修改或猜测后台配置。
503StorageUnavailable暂时无法签发或确认存储凭证。保留上传标识,稍后查询原任务。
403WritesDisabled当前账号尚未开放上传或签名写入。检查开发者中心的写入状态。
429UploadLimit上传并发名额用尽。先完成已有上传,按退避时间重试。
422QuotaExceeded文件大小或账号可用空间不足。核对上传上限和剩余空间。
409UploadConflict上传任务当前状态不允许此操作。使用原上传任务 ID 查询状态。
409UploadBusy上传任务正在处理。保留原任务 ID 和幂等键,等待当前处理完成。
409PartConflict该分片与原申报不一致。核对上传任务、分片序号及原文件字节的摘要。
404PartMissing存储尚未确认该片。重新申请同一分片的票据并传输原字节。
409PartsIncomplete尚有分片未确认。查询分片列表并补齐后再提交整包。

企业签名、密钥开通与产物

HTTP错误码处理说明
503JobResultUnavailable暂时无法关联任务与签名产物。保存应用 ID、签名任务 ID 和 request_id,稍后查询原任务,不用版本列表第一项代替。
503EntitlementsUnavailable签名权益、证书或站点配置暂不可用。保存 request_id,稍后查询原应用。
403RedemptionsDisabled账号尚未开放 API 密钥核销或写入。在开发者中心核对接入状态,并为自己的 API 应用授予 RedeemKeys。
503RedemptionsUnavailable密钥开通暂不可用。保留原幂等键和 request_id,先查询原核销回执,不要另建核销请求。
403RedemptionIpRequired在 API 应用配置出口 IP 白名单;IPv4 至少 /24、IPv6 至少 /64,越精确越好。
409RedemptionConfirmationRequired向使用者明确说明密钥开通不支持退款,确认后传 true。
403 / 409 / 422RedemptionRejected开通密钥不存在、已使用,或套餐、证书、目标应用不可用。核对完整开通密钥与应用 ID;AccessKey 用于 API 认证,不能代替开通密钥。
409CodeAlreadyRedeemed密钥已核销。响应丢失时使用原正文和原幂等键恢复;已保存核销回执 ID 时查询原回执。
409SigningNotActive当前签名权益或应用状态不可用。检查套餐有效期及签名状态。
429JobLimit签名任务达到并发或数量限制。查询已受理任务并按限额退避。

报价、预算与付款

HTTP错误码处理说明
503PricingUnavailable当前定价配置暂不可用。稍后重新读取套餐价格。
403PaymentsDisabled此账号的 API 付款尚未开放。核对账号付款许可与 API 应用的付款动作。
403BudgetDisabled当前 API 应用尚未开启费用预算。在开发者中心配置并启用预算后,再确认付款。
409CurrencyChanged金额单位已变化。重新读取价格、报价和预算并确认;退款先核对原订单,不自行换算金额。
403PaymentQuarantined账号账务正在复核,暂停新增付款或退款。联系平台核对原记录,修改预算不能解除限制。
409FinancialReviewRequired原付款账务需要复核。保存原订单 ID 和 request_id,联系平台处理,不重复退款或调整金额。
429QuoteLimit待消费报价或报价请求超过限制。优先使用仍有效的原报价。
422InsufficientBalance站内可用余额不足。核对金额、单位和余额后再决定是否购买。
409BudgetExceeded本次支付将超出单笔、日或月预算。检查账号层和 API 应用层的可用额度。
409QuoteExpired报价已过期。重新报价并由用户再次确认金额。
409QuoteAlreadyPaid报价已经消费。读取原报价和已完成的回执。
409QuoteApplicationChanged业务应用或安装上限已变。重新读取应用,报价并确认。
409PaymentConfirmationRequired确认字段与原报价不符。核对金额、价格修订号和金额单位修订号。
403FinancialIpRequired此操作需要精确来源 IP。核对服务端实际出口和该 API 应用授权。
403BillingDisabled账号尚未开放财务读取。单独申请对应查询能力。
503BillingUnavailable财务数据暂时不可用。记录 request_id 后稍后查询。
503PaymentsUnavailable支付或预算数据暂时不可用。请先查询原报价或回执。

退款与安装量扩容

HTTP错误码处理说明
503RefundsUnavailable暂时无法核实退款或权益数据,保留原订单号和 request_id。
422RefundRejected订单不满足当前退款规则。重新查询资格、截止时间和返回说明。
409RefundConfirmationRequired退款金额、单位或撤销权益的确认值不符。重新核对原订单。
409RefundAlreadyCompleted该笔订单已完成退款。查询原回执核对入账。
403RefundsDisabled账号当前未开放新退款。已有退款结果通过原订单查询。
403CapacityDisabled账号尚未开放安装量扩容购买。检查独立扩容准入。
400InvalidQuantity检查增加的设备数量和当前允许范围。
503CapacityUnavailable扩容报价或回执暂不可用。保存报价 ID,稍后查询原记录。

统计与设备数据

HTTP错误码处理说明
403StatisticsDisabled账号尚未开放统计查询。核对统计准入及对应读权限。
503StatisticsUnavailable留存数据暂不可用。保留 request_id,稍后重新读取。
403PrivacyDisabled账号尚未获得设备隐私数据准入,需单独开通。
429PrivacyQuotaExceeded账号当日设备行数额度不足。请依据 Retry-After 再查询。

限流与服务可用性

HTTP错误码处理说明
429Throttled请求达到限额,按 Retry-After 返回的秒数等待,再以新 nonce 发起请求。
503Unavailable服务暂时不可用。记录 request_id。涉及写入时,先查询该次操作的结果。
503PlatformDisabled平台 API 当前未开放,请在开发者中心查看接入状态。
503PolicyUnavailable暂时无法核对授权配置。保存 request_id 后稍后重试,不通过扩大权限绕过。
503CredentialServiceUnavailable认证或临时凭据签发服务暂不可用。保留原请求和幂等键,稍后核对结果。