标准错误响应

本文档介绍了 Google API 返回的一些错误代码和消息。具体而言，文中列出的错误都是在 Google API 的全局网域（即默认网域）中发生的。很多 API 还会指定自己的网域，用以标识不在全局网域中而仅在该 API 范围内的错误。对于这类错误，JSON 响应中 domain 属性的值将会是一个 API 范围内的值，例如 youtube.parameter。

本页面根据 RFC 7231 中定义的 HTTP 状态代码列出了这类错误。

以下 JSON 响应示例展示了系统如何表述全局错误：

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "invalidParameter",
    "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]",
    "locationType": "parameter",
    "location": "chart"
   }
  ],
  "code": 400,
  "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]"
 }
}

错误

  1. MOVED_PERMANENTLY (301)
  2. SEE_OTHER (303)
  3. NOT_MODIFIED (304)
  4. TEMPORARY_REDIRECT (307)
  5. BAD_REQUEST (400)
  6. UNAUTHORIZED (401)
  7. PAYMENT_REQUIRED (402)
  8. FORBIDDEN (403)
  9. NOT_FOUND (404)
  10. METHOD_NOT_ALLOWED (405)
  11. CONFLICT (409)
  12. GONE (410)
  13. PRECONDITION_FAILED (412)
  14. REQUEST_ENTITY_TOO_LARGE (413)
  15. REQUESTED_RANGE_NOT_SATISFIABLE (416)
  16. EXPECTATION_FAILED (417)
  17. PRECONDITION_REQUIRED (428)
  18. TOO_MANY_REQUESTS (429)
  19. INTERNAL_SERVER_ERROR (500)
  20. NOT_IMPLEMENTED (501)
  21. SERVICE_UNAVAILABLE (503)

MOVED_PERMANENTLY (301)

错误代码 说明
movedPermanently 此请求及今后对同一操作的请求必须发送到在此响应的 Location 标头中指定的网址，而不是此请求被发送到的那个网址。

SEE_OTHER (303)

错误代码 说明
seeOther 您的请求已成功处理。要获得响应，请向 Location 标头中指定的网址发送 GET 请求。
mediaDownloadRedirect 您的请求已成功处理。要获得响应，请向 Location 标头中指定的网址发送 GET 请求。

NOT_MODIFIED (304)

错误代码 说明
notModified 不符合为 If-None-Match 标头设置的条件。此响应表明所请求的文档尚未修改，应当检索缓存的响应。请检查 If-None-Match HTTP 请求标头的值。

TEMPORARY_REDIRECT (307)

错误代码 说明
temporaryRedirect 要使您的请求得到处理，请将其重新发送到在此响应的 Location 标头中指定的网址。

BAD_REQUEST (400)

错误代码 说明
badRequest 该 API 请求无效或格式不正确。因此，API 服务器无法解读该请求。
badBinaryDomainRequest 该二进制网域请求无效。
badContent 请求数据的内容类型或多部分请求中某一部分的内容类型不受支持。
badLockedDomainRequest 锁定的网域请求无效。
corsRequestWithXOrigin 该 CORS 请求包含 XD3 跨域标头，表明这是一个错误的 CORS 请求。
endpointConstraintMismatch 由于与指定的 API 不符，因此请求失败。请检查网址路径的值，以确保其正确无误。
invalid 由于包含无效值，因此请求失败。该值可能是参数值、标头值或属性值。
invalidAltValue alt 参数值指定了一个未知输出格式。
invalidHeader 由于包含无效标头，因此请求失败。
invalidParameter 由于包含无效参数或参数值，因此请求失败。请查看 API 文档，以确定哪些参数对您的请求来说有效。
invalidQuery 该请求无效。请查看 API 文档，以确定该请求支持哪些参数，同时查看该请求是否包含无效的参数组合或无效的参数值。请检查 q 请求参数的值。
keyExpired 该请求中提供的 API 密钥已过期，这意味着 API 服务器无法查看发出该请求的应用的配额限制。请查看 Google Developers Console 了解详情或获取新密钥。
keyInvalid 该请求中提供的 API 密钥无效，这意味着 API 服务器无法查看发出该请求的应用的配额限制。请在 Google Developers Console 中查找您的 API 密钥或再获取一个。
lockedDomainCreationFailure OAuth 令牌是在查询字符串中收到的，而此 API 禁止对 JSON 或 XML 之外的响应格式使用查询字符串。如果可能，请尝试在授权标头中发送 OAuth 令牌。
notDownload 只能向 /download/* 网址路径发送媒体下载请求。请向同一个路径重新发送该请求，但要去掉 /download 前缀。
notUpload 由于不是上传请求，因此请求失败。只能向 /upload/* URI 发送上传请求。请尝试向同一个路径重新发送该请求，但要去掉 /upload 前缀。
parseError API 服务器无法解析请求正文。
required 该 API 请求缺少必需的信息。必需信息可能是参数，也可能是资源属性。
tooManyParts 由于包含的部分过多，因此该多部分请求失败了。
unknownApi 系统无法识别该请求调用的 API。
unsupportedMediaProtocol 客户端使用的媒体协议不受支持。
unsupportedOutputFormat 此服务不支持 alt 参数值指定的输出格式。请检查 alt 请求参数的值。
wrongUrlForUpload 该请求是上传请求，但由于未发送到正确的 URI，因此请求失败。上传请求必须发送到包含 /upload/* 前缀的 URI。请尝试向同一个路径重新发送该请求，但要包含 /upload 前缀。

UNAUTHORIZED (401)

错误代码 说明
unauthorized 用户无权发出该请求。
authError 为该请求提供的授权凭据无效。请检查 Authorization HTTP 请求标头的值。
expired 会话超时。请检查 Authorization HTTP 请求标头的值。
lockedDomainExpired 由于之前有效的锁定网域已过期，因此请求失败。
required 用户必须登录才能发出此 API 请求。请检查 Authorization HTTP 请求标头的值。

PAYMENT_REQUIRED (402)

错误代码 说明
dailyLimitExceeded402 已达到开发者设置的每日预算上限。
quotaExceeded402 所请求的操作需要的资源超出配额允许的上限。需要付款才能完成该操作。
user402 所请求的操作需要已通过身份验证的用户完成某种付款。

FORBIDDEN (403)

错误代码 说明
forbidden 所请求的操作已被禁止，无法完成。
accessNotConfigured 您的项目未配置此 API 的访问权限。请在 Google Developers Console 中为您的项目激活此 API。
accessNotConfigured 项目由于存在滥用行为而被阻止。请参阅 http://support.google.com/code/go/developer_compliance。
accessNotConfigured 项目已被标为待删除。
accountDeleted 与该请求的授权凭据相关联的用户账号已被删除。请检查 Authorization HTTP 请求标头的值。
accountDisabled 与该请求的授权凭据相关联的用户账号已被停用。请检查 Authorization HTTP 请求标头的值。
accountUnverified 发出该请求的用户的电子邮件地址尚未经过验证。请检查 Authorization HTTP 请求标头的值。
concurrentLimitExceeded 由于已达到并发使用上限，因此请求失败。
dailyLimitExceeded 已达到该 API 的每日配额上限。
dailyLimitExceeded 已达到每日配额上限，并且项目由于存在滥用行为已被阻止。请参阅 Google API 合规性支持表单，获取解决该问题的相关帮助。
dailyLimitExceededUnreg 由于已达到未经身份验证情况下该 API 的每日使用上限，因此请求失败。要继续使用该 API，则需要在 Google Developers Console 中进行注册。
downloadServiceForbidden 该 API 不支持下载服务。
insufficientAudience 无法对此受众群体完成该请求。
insufficientAuthorizedParty 无法对此应用完成该请求。
insufficientPermissions 通过身份验证的用户权限不足，无法执行此请求。
limitExceeded 由于访问权限或速率限制，系统无法完成该请求。
lockedDomainForbidden 此 API 不支持锁定的网域。
quotaExceeded 所请求的操作需要的资源超出配额允许的上限。
rateLimitExceeded 在指定时间范围内发送的请求过多。
rateLimitExceededUnreg 已超出速率限制，您必须注册您的应用才能继续调用该 API。请在 Google Developers Console 中进行注册。
responseTooLarge 请求的资源过大，无法返回。
servingLimitExceeded 已达到为该 API 指定的整体速率上限。
sslRequired 需要使用 SSL 才能执行此操作。
unknownAuth API 服务器未识别出用于该请求的授权方案。请检查 Authorization HTTP 请求标头的值。
userRateLimitExceeded 由于已达到每个用户的速率上限，因此请求失败。
userRateLimitExceededUnreg 由于已达到每个用户的速率上限，系统无法完成该请求，并且在请求中未识别出客户端开发者。请使用 Google Developers Console (https://console.developers.google.com) 为您的应用创建一个项目。
variableTermExpiredDailyExceeded 由于不定期限配额已过期并且已达到每日上限，系统无法完成该请求。
variableTermLimitExceeded 由于已达到不定期限配额上限，因此请求失败。

NOT_FOUND (404)

错误代码 说明
notFound 由于找不到与该请求关联的资源，因此所请求的操作失败了。
notFound 找不到与该请求关联的资源。如果您在过去两周内未用过此 API，请重新部署 App Engine 应用，然后再次尝试调用此 API。
unsupportedProtocol 该请求中使用的协议不受支持。

METHOD_NOT_ALLOWED (405)

错误代码 说明
httpMethodNotAllowed 与该请求关联的 HTTP 方法不受支持。

CONFLICT (409)

错误代码 说明
conflict 由于请求的操作会与现有条目产生冲突，因此系统无法完成该 API 请求。例如，尝试创建重复条目的请求将会产生冲突，不过重复条目通常会通过更具体的错误进行标识。
duplicate 由于所请求的操作尝试创建已存在的资源，因此操作失败。

GONE (410)

错误代码 说明
deleted 由于与该请求关联的资源已被删除，因此请求失败。

PRECONDITION_FAILED (412)

错误代码 说明
conditionNotMet 不符合在该请求的 If-Match 或 If-None-Match HTTP 请求标头中设置的条件。请参阅 HTTP 规范的 ETag 部分了解详情，并检查 If-Match HTTP 请求标头的值。

REQUEST_ENTITY_TOO_LARGE (413)

错误代码 说明
backendRequestTooLarge 该请求太大。
batchSizeTooLarge 该批量请求中包含的元素过多。
uploadTooLarge 由于在该请求中发送的数据过大，因此请求失败。

REQUESTED_RANGE_NOT_SATISFIABLE (416)

错误代码 说明
requestedRangeNotSatisfiable 无法满足该请求指定的范围。

EXPECTATION_FAILED (417)

错误代码 说明
expectationFailed 服务器无法实现客户端预期目标。

PRECONDITION_REQUIRED (428)

错误代码 说明
preconditionRequired 未提供该请求所需的先决条件。要成功完成该请求，您需在请求中提供 If-Match 或 If-None-Match 标头。

TOO_MANY_REQUESTS (429)

错误代码 说明
rateLimitExceeded 在指定时间范围内发送的请求过多。

INTERNAL_SERVER_ERROR (500)

错误代码 说明
internalError 由于出现内部错误，因此请求失败。

NOT_IMPLEMENTED (501)

错误代码 说明
notImplemented 请求的操作尚未执行。
unsupportedMethod 由于该请求尝试执行未知方法或操作，因此请求失败。

SERVICE_UNAVAILABLE (503)

错误代码 说明
backendError 发生后端错误。
backendNotConnected 由于出现连接错误，因此请求失败。
notReady API 服务器尚未准备好接受请求。