错误响应

如果 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 服务不可用 服务暂时不可用。这通常是暂时性问题。建议使用指数退避算法重试请求。为避免超出服务器错误配额，请务必实现带重试限制的指数退避算法。