错误响应

当 API 请求成功时，API 会返回 200 OK 状态代码，并在响应正文中返回所请求的数据。如果发生错误，API 会返回 Google API 定义的规范错误代码之一（映射到 HTTP 状态代码），以及包含错误信息的响应正文。遇到错误时，请检查 JSON 响应正文中的 message 和 status 字段，获取有助于调试的详细信息。

错误格式

如果请求导致错误，API 会返回相应的 HTTP 状态代码和 JSON 响应正文。错误响应包含一个 error 对象，其结构如下：

{
  "error": {
    "code": 403,
    "message": "User does not have sufficient permissions for this property.",
    "status": "PERMISSION_DENIED"
  }
}

error 对象包含以下字段：

字段 说明
代码 HTTP 状态代码，例如 400、401、403、429 或 500。
消息 错误的简短描述。
状态 规范错误代码，例如 INVALID_ARGUMENT、UNAUTHENTICATED、PERMISSION_DENIED、RESOURCE_EXHAUSTED 或 INTERNAL。

常见错误

下表列出了 API 返回的常见错误。

HTTP 状态代码 规范代码 原因 说明
400 INVALID_ARGUMENT 请求无效 请求格式不正确。这可能是因为缺少或存在无效的参数，例如日期范围不正确或过滤条件格式有误。
401 UNAUTHENTICATED 凭据无效 请求没有目标资源的有效身份验证凭据。如果 OAuth 2.0 访问令牌缺失、无效或已过期，可能会出现此问题。按照使用 OAuth 2.0 进行身份验证中的说明获取有效令牌。
403 PERMISSION_DENIED 权限不足 通过身份验证的用户无权访问所请求的 Google Analytics 媒体资源。
429 RESOURCE_EXHAUSTED 超出了配额 由于已达到 API 配额上限，因此请求被拒绝。如需了解详情，请参阅Google Data API 限制和配额。您可能超出了每个项目或每项媒体资源的限制。
500 INTERNAL 内部服务器错误 服务器出现意外错误。这通常是暂时性问题。建议使用指数退避算法重试请求。为避免超出服务器错误配额，请务必实现带重试次数上限的指数退避算法。
503 UNAVAILABLE 服务不可用 服务暂时不可用。这通常是暂时性问题。建议使用指数退避算法重试请求。为避免超出服务器错误配额，请务必实现带重试次数上限的指数退避算法。