审校于 2026-11-10 · API 版本 2026-11-09 · 阅读 Markdown
错误、重试与恢复
API 错误使用 { "error": { "code": "…", "message": "…", "requestId": "…" } },并带有可选的字段错误、目标错误、重试提示和操作交接。保留 requestId 以便支持。收集诊断时不要记录凭据、签名上传 URL 或敏感请求内容。
| 响应 | 恢复 |
|---|---|
401 unauthenticated | 检查缺失、格式错误或已撤销的产品密钥 |
403 forbidden_scope / account_not_allowed | 审查密钥作用域和目标访问权 |
402 account_limit、seat_limit、storage_limit | 审查工作区权益和资源使用 |
402 subscription_inactive / trial_expired | 解决账单状态;保留草稿和排队的工作 |
409 revision_conflict | 读取当前版本,审查更改并有意图地重新应用 |
409 idempotency_conflict | 密钥被用不同请求体复用;核对原始操作 |
409 consent_required | 请授权人员完成提供的审查交接 |
409 too_late_to_cancel | 检查实际交付状态;不要声称取消成功 |
media_expired / media_deleting | 重新上传原始文件并更新草稿 |
422 validation_failed | 修正结构化字段或按目标的问题 |
429 rate_limited | 遵守 Retry-After;降低并发并使用退避 |
submission_unknown | 在尝试另一次提交之前核对已有的外部结果 |
安全的变更重试
在第一次变更之前生成幂等键并存储其确切请求。如果响应丢失,操作可能已经成功。用相同密钥重放相同请求;绝不要仅因为网络超时就生成新密钥。MCP 变更工具会回显其密钥,包括在 transport_outcome_unknown 失败中。适配器不会自动重试变更。
技术性工作区限速不是发布额度。使用 /usage 获取当前套餐和速率信息。仅在适当时对瞬时错误退避;在不改变原因的情况下重试授权、校验或人类同意错误没有帮助。
部分成功与观察
已接受的发布/排期批次是一组独立的交付。保留成功的回执和原生链接。通过失败目标自己的重试端点恢复它,而不是重新创建整个批次。优先使用已签名的 webhooks;如果轮询,使用延迟递增的有界尝试次数,并将未解决的工作呈现给人员。