错误响应

当 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 配额上限，请求被拒绝。如需了解详情，请参阅 Data API 限制和配额。您可能超出了每个项目或每个媒体资源的限制。
500 INTERNAL 内部服务器错误 服务器出现意外错误。这通常是暂时性问题。建议使用指数退避算法重试请求。为避免超出服务器错误配额，请务必实现具有重试限制的指数退避算法。
503 UNAVAILABLE 服务不可用 服务暂时不可用。这通常是暂时性问题。建议使用指数退避算法重试请求。为避免超出服务器错误配额，请务必实现具有重试限制的指数退避算法。