错误处理、幂等与重试
本页内容
先区分请求失败和业务任务失败,再决定查询、等待或重试。写入响应丢失时,原操作可能已经成功,应先核对结果并保持原幂等键。
读取成功与错误响应
成功响应从 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 | 只读查询可有限重试;写入先确认原操作是否已受理或完成。 |
保存幂等键并重试
- 开始一次独立写操作时生成 16–64 位幂等键,并在首次请求前持久保存操作路径和正文。
- 重试时保持同一键、同一路径和相同正文,重新生成认证时间、nonce 与签名。
- 已保存资源 ID 时先查询原上传、任务、报价或订单。确需开展另一项业务时再使用新键。
幂等键不是可以无限期重建结果的凭证。各业务的恢复期限和回执规则不同,应遵循对应接口说明。签名工具对没有任务 ID 的提交恢复另有时间限制;财务操作优先按持久回执对账。
临时凭据、下载凭证和设备导出在重放时可能只返回回执,不再交付 Secret、URL 或导出内容。先检查响应,再明确决定是否需要发起新申请。
日期、金额、空值与两种认证请求头的区别,见请求与响应约定。异步任务失败与 HTTP 请求失败需要分开处理。
按问题查询错误码
先按错误码确定失败原因,再决定查询原结果、修改请求或稍后重试。下表列出业务 API 的错误;OAuth 见授权错误,Webhook 接收失败见通知排查。
共 87 个错误码
请求格式与并发冲突
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 400 | InvalidHost | 使用站点配置的 HTTPS 主域名,并用同一域名构造签名。 |
| 400 | InvalidRequest | 检查 GET 是否带正文,以及 POST 的 Content-Type 和幂等键。 |
| 413 | RequestTooLarge | 将管理 JSON 正文控制在 16 KiB 内。安装包文件应按上传凭证传到存储服务。 |
| 400 | HttpsRequired | 使用 HTTPS 网站主域名调用 API,并检查代理是否正确传递连接协议。 |
| 405 | MethodNotAllowed | 使用接口指定的 GET 或 POST 方法,不用方法覆盖请求头替代。 |
| 400 | InvalidQuery | 检查参数名称、格式、范围和 URI 编码,删除重复参数。 |
| 400 | InvalidInput | 按请求体字段表核对类型、枚举与必填项,排除未知或重复字段。 |
| 400 | InvalidCursor | 原游标已失效或与当前资源不匹配。保持筛选条件,从第一页重新查询。 |
| 409 | IdempotencyConflict | 同一个幂等键用于不同请求。恢复原请求的正文与路径。独立的新业务操作使用新键。 |
| 409 | RevisionConflict | 目标已被更新。重新读取当前版本或 revision,确认差异后再提交新的操作。 |
认证、授权与临时凭据
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 401 | InvalidCredentials | 凭据无效、已停用,或请求签名不匹配。核对 AK、环境、正文摘要和签名头。 |
| 401 | RequestExpired | 签名时间超出允许窗口。校准 UTC 时钟,生成新的日期、nonce 和签名。 |
| 409 | ReplayDetected | nonce 已使用。保留原业务幂等键,使用新的 nonce 签名。 |
| 403 | AccessDenied | 检查当前身份的动作、资源范围、来源 IP 及功能准入。 |
| 404 | NotFound | 核对路径中各标识是否完整、属于同一业务应用且在当前授权范围内。 |
| 403 | CorsDenied | 浏览器须使用已批准 Origin 的 OAuth 客户端。核对来源、方法和请求头,不在浏览器使用长期 Secret。 |
| 403 | SessionsDisabled | 账号尚未允许签发只读临时凭据。检查开发者中心的会话设置。 |
| 400 / 403 | InvalidPolicy | 核对申请的动作、应用、网络、时长和限额是否在父凭据授权范围内。 |
| 409 | ParentExpiring | 父密钥剩余有效期不足。缩短申请时长或使用有效父密钥。 |
| 429 | SessionLimit | 有效临时会话已满。撤销不用的会话或等待过期。 |
| 409 | CredentialExpiring | 父凭据剩余有效期不足。换用有效凭据再申请下载链接。 |
应用、发布与下载
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 429 | CreationLimit | 待完成的应用预留过多。先完成现有预留,或等待过期释放。 |
| 403 | ManagementDisabled | 账号尚未开放应用管理。到开发者中心查看应用管理准入。 |
| 400 | ConfirmationRequired | 删除确认值有误。显示目标应用并确认,传入与路径相同的完整应用 ID。 |
| 409 | ApplicationConflict | 当前应用状态不允许该变更。重新读取资料或当前发布版本。 |
| 409 | ApplicationUnavailable | 应用状态已变化或当前不可操作。先核对应用详情和权益。 |
| 409 | CreationConflict | 应用预留已过期、已完成或已有上传任务。先查询应用创建状态与原上传任务,再决定是否重新创建应用预留。 |
| 422 | RollbackUnsupported | 目标历史签名包不满足回滚条件。核对证书、设备校验和版本状态。 |
| 403 | DownloadsDisabled | 该账号或包类型尚未开放下载凭证。核对原包和签名包的独立授权。 |
| 422 | PackageUnavailable | 指定版本没有请求的可用产物。重新检查版本和包类型。 |
| 403 | SettingsDisabled | 账号尚未开放分发设置修改,需单独取得准入。 |
| 503 | SettingsUnavailable | 分发设置暂不可用。保留原 revision,稍后重新读取并核对,不假定保存已成功。 |
上传与存储
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 422 | StorageUnsupported | 当前请求的文件传输方式不可用。上传请使用 SDK 上传助手或通用分片流程,无需选择存储厂商;下载请保留 request_id 联系平台。 |
| 422 | StorageUnverified | 文件传输服务暂不可用。保留原上传任务 ID 和 request_id 联系平台,不修改或猜测后台配置。 |
| 503 | StorageUnavailable | 暂时无法签发或确认存储凭证。保留上传标识,稍后查询原任务。 |
| 403 | WritesDisabled | 当前账号尚未开放上传或签名写入。检查开发者中心的写入状态。 |
| 429 | UploadLimit | 上传并发名额用尽。先完成已有上传,按退避时间重试。 |
| 422 | QuotaExceeded | 文件大小或账号可用空间不足。核对上传上限和剩余空间。 |
| 409 | UploadConflict | 上传任务当前状态不允许此操作。使用原上传任务 ID 查询状态。 |
| 409 | UploadBusy | 上传任务正在处理。保留原任务 ID 和幂等键,等待当前处理完成。 |
| 409 | PartConflict | 该分片与原申报不一致。核对上传任务、分片序号及原文件字节的摘要。 |
| 404 | PartMissing | 存储尚未确认该片。重新申请同一分片的票据并传输原字节。 |
| 409 | PartsIncomplete | 尚有分片未确认。查询分片列表并补齐后再提交整包。 |
企业签名、密钥开通与产物
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 503 | JobResultUnavailable | 暂时无法关联任务与签名产物。保存应用 ID、签名任务 ID 和 request_id,稍后查询原任务,不用版本列表第一项代替。 |
| 503 | EntitlementsUnavailable | 签名权益、证书或站点配置暂不可用。保存 request_id,稍后查询原应用。 |
| 403 | RedemptionsDisabled | 账号尚未开放 API 密钥核销或写入。在开发者中心核对接入状态,并为自己的 API 应用授予 RedeemKeys。 |
| 503 | RedemptionsUnavailable | 密钥开通暂不可用。保留原幂等键和 request_id,先查询原核销回执,不要另建核销请求。 |
| 403 | RedemptionIpRequired | 在 API 应用配置出口 IP 白名单;IPv4 至少 /24、IPv6 至少 /64,越精确越好。 |
| 409 | RedemptionConfirmationRequired | 向使用者明确说明密钥开通不支持退款,确认后传 true。 |
| 403 / 409 / 422 | RedemptionRejected | 开通密钥不存在、已使用,或套餐、证书、目标应用不可用。核对完整开通密钥与应用 ID;AccessKey 用于 API 认证,不能代替开通密钥。 |
| 409 | CodeAlreadyRedeemed | 密钥已核销。响应丢失时使用原正文和原幂等键恢复;已保存核销回执 ID 时查询原回执。 |
| 409 | SigningNotActive | 当前签名权益或应用状态不可用。检查套餐有效期及签名状态。 |
| 429 | JobLimit | 签名任务达到并发或数量限制。查询已受理任务并按限额退避。 |
报价、预算与付款
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 503 | PricingUnavailable | 当前定价配置暂不可用。稍后重新读取套餐价格。 |
| 403 | PaymentsDisabled | 此账号的 API 付款尚未开放。核对账号付款许可与 API 应用的付款动作。 |
| 403 | BudgetDisabled | 当前 API 应用尚未开启费用预算。在开发者中心配置并启用预算后,再确认付款。 |
| 409 | CurrencyChanged | 金额单位已变化。重新读取价格、报价和预算并确认;退款先核对原订单,不自行换算金额。 |
| 403 | PaymentQuarantined | 账号账务正在复核,暂停新增付款或退款。联系平台核对原记录,修改预算不能解除限制。 |
| 409 | FinancialReviewRequired | 原付款账务需要复核。保存原订单 ID 和 request_id,联系平台处理,不重复退款或调整金额。 |
| 429 | QuoteLimit | 待消费报价或报价请求超过限制。优先使用仍有效的原报价。 |
| 422 | InsufficientBalance | 站内可用余额不足。核对金额、单位和余额后再决定是否购买。 |
| 409 | BudgetExceeded | 本次支付将超出单笔、日或月预算。检查账号层和 API 应用层的可用额度。 |
| 409 | QuoteExpired | 报价已过期。重新报价并由用户再次确认金额。 |
| 409 | QuoteAlreadyPaid | 报价已经消费。读取原报价和已完成的回执。 |
| 409 | QuoteApplicationChanged | 业务应用或安装上限已变。重新读取应用,报价并确认。 |
| 409 | PaymentConfirmationRequired | 确认字段与原报价不符。核对金额、价格修订号和金额单位修订号。 |
| 403 | FinancialIpRequired | 此操作需要精确来源 IP。核对服务端实际出口和该 API 应用授权。 |
| 403 | BillingDisabled | 账号尚未开放财务读取。单独申请对应查询能力。 |
| 503 | BillingUnavailable | 财务数据暂时不可用。记录 request_id 后稍后查询。 |
| 503 | PaymentsUnavailable | 支付或预算数据暂时不可用。请先查询原报价或回执。 |
退款与安装量扩容
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 503 | RefundsUnavailable | 暂时无法核实退款或权益数据,保留原订单号和 request_id。 |
| 422 | RefundRejected | 订单不满足当前退款规则。重新查询资格、截止时间和返回说明。 |
| 409 | RefundConfirmationRequired | 退款金额、单位或撤销权益的确认值不符。重新核对原订单。 |
| 409 | RefundAlreadyCompleted | 该笔订单已完成退款。查询原回执核对入账。 |
| 403 | RefundsDisabled | 账号当前未开放新退款。已有退款结果通过原订单查询。 |
| 403 | CapacityDisabled | 账号尚未开放安装量扩容购买。检查独立扩容准入。 |
| 400 | InvalidQuantity | 检查增加的设备数量和当前允许范围。 |
| 503 | CapacityUnavailable | 扩容报价或回执暂不可用。保存报价 ID,稍后查询原记录。 |
统计与设备数据
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 403 | StatisticsDisabled | 账号尚未开放统计查询。核对统计准入及对应读权限。 |
| 503 | StatisticsUnavailable | 留存数据暂不可用。保留 request_id,稍后重新读取。 |
| 403 | PrivacyDisabled | 账号尚未获得设备隐私数据准入,需单独开通。 |
| 429 | PrivacyQuotaExceeded | 账号当日设备行数额度不足。请依据 Retry-After 再查询。 |
限流与服务可用性
| HTTP | 错误码 | 处理说明 |
|---|---|---|
| 429 | Throttled | 请求达到限额,按 Retry-After 返回的秒数等待,再以新 nonce 发起请求。 |
| 503 | Unavailable | 服务暂时不可用。记录 request_id。涉及写入时,先查询该次操作的结果。 |
| 503 | PlatformDisabled | 平台 API 当前未开放,请在开发者中心查看接入状态。 |
| 503 | PolicyUnavailable | 暂时无法核对授权配置。保存 request_id 后稍后重试,不通过扩大权限绕过。 |
| 503 | CredentialServiceUnavailable | 认证或临时凭据签发服务暂不可用。保留原请求和幂等键,稍后核对结果。 |
未找到匹配的错误码,请缩短关键词或按 HTTP 状态查询。