エラーレスポンス

GraphQL Analytics API は HTTPS リクエストと JSON レスポンスに基づく RESTful API であり、使い慣れた HTTP ステータスコード（例: 404、500、504）を返します。ただし一般的な REST とは異なり、200 レスポンスにエラーが含まれることがあります。これは GraphQL 仕様 ↗ に従っています。

すべてのレスポンスに errors 配列があります。エラーがなければ null になり、エラーがあれば少なくとも 1 つのエラーオブジェクトが含まれます。null でないエラーオブジェクトには、次のフィールドがあります。

message: エラーを説明する文字列です。
path: ルートから始まる、エラーに関連するノードです。パス配列に含まれる番号（例: 0 または 1）は、エラーがどのゾーンに適用されるかを示します。0 はリストの最初のゾーン（クエリ対象が 1 ゾーンだけの場合はそのゾーン）です。
timestamp: エラーが発生した UTC 日時です。

例

{
  "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）

これらのメッセージは、一時的なサーバー側の問題を示します。1 つ目は、通常、上流のデータベースに到達できないか、データベースがエラーを返したことを意味します。2 つ目は、サーバーが同時クエリ数の上限に達したことを意味します。

少し待ってからリクエストを再試行してください。エラーが続く場合は、進行中のインシデントがないか 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）

これらのメッセージは、現在のプラン ↗ でそのデータセットに許可されている範囲をクエリが超えていることを示します。アップグレードを検討してください。詳細はノードの制限を参照してください。

パースの問題

エラーメッセージの例:

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 スキーマと照合して構文を確認し、無効なフィールドや構造を修正してください。

レート制限を超過

エラーメッセージの例:

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）

これらのメッセージは、クエリがレート制限またはリソース制限を超えたことを示します。クエリの複雑さ、リクエストあたりのゾーン数やアカウント数を減らすか、再試行まで待ってください。レート制限の詳細は 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 トークンまたはベアラートークンが欠落している、期限切れ、または無効であることを意味します。Authorization ヘッダーに有効なトークンを渡しているか確認してください。

403 レスポンスは、トークンにリクエストしたアカウントまたはゾーンに必要な権限がないことを意味します。対象リソースに対して Analytics: Read 権限があるか確認してください。詳細は Tokens を参照してください。

内部サーバーエラー

エラーメッセージの例:

Internal server error（HTTP 500）

予期しない障害を示す汎用エラーです。続く場合は、HTTP レスポンスの Ray-ID ヘッダーを含め、リクエストとレスポンス一式を添えて Cloudflare Support ↗ に連絡してください。