参考

错误和速率限制

REST 错误使用此信封。保留请求 ID 以获取支持，并且切勿记录您的 API 密钥：

先看 code 和 requestId

稳定的 code 用于告诉程序发生了什么；message 用自然语言解释这次请求；联系支持时请保留 requestId。

JSON error response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The API key is missing, invalid, or revoked.",
    "requestId": "req_..."
  }
}

遇到 401 时，检查请求头是否以 Bearer 开头、后面是否有一个空格，以及密钥是否有效。遇到 403 时，检查账号套餐和创建密钥时选择的权限范围。

遇到 409 或 422 时，确认 PUT 已完成、Content-Type 一致，并且上传字节数等于 sizeBytes。如果临时 URL 已过期，请重新创建上传任务。

代码	HTTP	含义
BAD_REQUEST	400 / 409	HTTP 400 表示请求正文无效；HTTP 409 表示上传在当前状态下无法完成。
UNAUTHORIZED	401	API 密钥丢失、无效或已撤销。
PAID_PLAN_REQUIRED	403	该帐户没有符合条件的付费计划。
INSUFFICIENT_SCOPE	403	API 密钥不包含所需的权限范围。
NOT_FOUND	404	找不到拥有的上传、文件或共享。
UPLOAD_NOT_READY	409	上传的对象尚未准备好完成。
FILE_TOO_LARGE	413	文件超出了适用的大小限制。
OBJECT_VALIDATION_FAILED	422	上传的对象验证失败。
QUOTA_EXCEEDED	429	上传配额已用完。
RATE_LIMIT_EXCEEDED	429	已超出 API 请求频率限制。
SERVICE_UNAVAILABLE	503	所需的服务暂时不可用。

遇到 429 时，只能在 Retry-After 指定的时间后重试。临时 503 错误使用指数退避重试。无效的 400、401 或 403 请求不要自动重试。