错误响应

GraphQL Analytics API 是基于 HTTPS 请求和 JSON 响应的 RESTful API，将返回熟悉的 HTTP 状态码（例如 404、500、504）。但是，与常见的 REST 方法不同，200 响应可能包含错误，符合 GraphQL 规范 ↗。

所有响应都包含 errors 数组，如果没有错误则为 null，如果有错误则至少包含一个 error 对象。非 null error 对象包含以下字段：

• message：描述错误的字符串。
• path：与错误关联的节点，从根开始。请注意 path 数组中包含的数字（例如 0 或 1）指定错误适用于哪个 zone；0 表示列表中的第一个 zone（或如果只查询一个 zone，则为唯一 zone）。
• timestamp：错误发生时的 UTC datetime。

{
  "data": null,
  "errors": [
    {
      "message": "cannot request data older than 2678400s",
      "path": ["viewer", "zones", "0", "firewallEventsAdaptiveGroups"],
      "extensions": {
        "timestamp": "2019-12-09T21:27:19.195060142Z"
      }
    }
  ]
}

示例错误消息：

• unable to execute query, please try again later（HTTP 503）
• too many queries in progress, please try again later（HTTP 503）

这些消息表示临时服务器端问题。第一条消息通常意味着上游数据库不可达或返回错误。第二条消息表示服务器已达到最大并发查询数。

短暂延迟后重试请求。如果错误持续，请检查 Cloudflare 状态页面 ↗ 了解正在发生的事件。

示例错误消息：

• cannot request data older than...（HTTP 400）
• number of fields can't be more than...（HTTP 400）
• limit must be positive number and not greater than...（HTTP 400）
• query time range is too large...（HTTP 400）

这些消息表示查询超出当前计划 ↗下特定数据集允许的范围，应考虑升级。详情请参阅 Node limits。

示例错误消息：

• error parsing args...（HTTP 400）
• scalar fields must have no selections（HTTP 400）
• object field must have selections（HTTP 400）
• unknown field...（HTTP 400）
• query contains error, please review it and retry（HTTP 400）

这些消息表示查询格式错误无法处理。请根据 GraphQL schema 检查查询语法并修正无效字段或结构。

示例错误消息：

• rate limiter budget depleted, try again after 5 minutes（HTTP 429）
• in combination, your request queries too many nodes, zones and accounts（HTTP 429）
• query consumed excessive resources, please try running smaller queries which consume fewer resources（HTTP 429）

这些消息表示查询超出速率或资源限制。减少查询复杂度、每个请求的 zone 或 account 数量，或等待后重试。有关速率限制的更多详情，请参阅 Limits 部分。

示例错误消息：

• Unauthorized（HTTP 401）
• not authorized for that account（HTTP 403）
• zones [...] are not authorized（HTTP 403）
• does not have access to the path...（HTTP 403）

Unauthorized 响应表示 API token 或 bearer token 缺失、过期或无效。验证你在 Authorization header 中传递了有效 token。

403 响应表示 token 没有请求 account 或 zone 所需的权限。验证 token 对相关资源具有 Analytics: Read 权限。更多详情，请参阅 Tokens 部分。

示例错误消息：

• Internal server error（HTTP 500）

这是表示意外失败的通用错误。如果持续出现，请联系 Cloudflare Support ↗，提供完整请求和响应，包括 HTTP 响应中的 Ray-ID header。