​
概要

Analytics API（アナリティクス API）は、無効なクエリのデバッグに役立つ詳細なエラーメッセージを返します。本ページでは、よくあるエラーのシナリオとその解決方法を説明します。

​
エラーレスポンス形式

エラーが発生すると、API は内容を説明するメッセージ付きのエラーレスポンスを返します。 
{
  "error": "何が問題だったかを説明するエラーメッセージ"
}

​
よくあるエラー

​
認証エラー

エラー: Invalid service key原因: 提供されたサービスキーが無効であるか、失効しています。解決策:
  • サービスキーが正しいか確認する
  • サービスキーが失効していないか確認する
  • 必要に応じて新しいサービスキーを発行する
エラー: Insufficient permissions原因: サービスキーに必要な “Teams Read-only” 権限がありません。解決策:
  • チーム設定でサービスキーの権限を更新する
  • サービスキーに “Teams Read-only” アクセス権が付与されていることを確認する

​
クエリ構造のエラー

エラー: at least one field or aggregation is required原因: クエリリクエストに selections または 集計 が含まれていません。解決策: クエリリクエストに少なくとも1つの selection を追加してください:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
エラー: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED原因: data_source フィールドにタイプミスがある可能性があります。解決策: データソースの綴りを再確認してください。利用可能な選択肢:
  • QUERY_DATA_SOURCE_USER_DATA
  • QUERY_DATA_SOURCE_CHAT_DATA
  • QUERY_DATA_SOURCE_COMMAND_DATA
  • QUERY_DATA_SOURCE_PCW_DATA
エラー: all selection fields should have an aggregation function, or none of them should原因: 一部の selections に集計関数が設定されている一方、他には設定されていません。解決策: すべての selections に集計関数を追加するか、すべてから削除してください:不正な例:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]
正しい例:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​
フィールドと集計のエラー

エラー: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM原因: 指定されたフィールド型では、その集計関数はサポートされていません。解決策: 各フィールドで有効な集計関数はどれか、Available Fields セクションを確認してください。文字列フィールドは通常、COUNT と UNSPECIFIED のみをサポートします。
エラー: tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]原因: “distinct_*” パターンのフィールドは、aggregations セクションでは使用できません。解決策: 提案された代替フィールドで集計してください。無効:
"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]
有効:
"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]
エラー: duplicate field alias for selection/aggregation: num_acceptances原因: 複数の selections または aggregations で同じ名前が使われています。解決策: すべてのフィールドエイリアスが一意であることを確認してください。名前を指定しない場合、デフォルトで {aggregation_function}_{field_name} になります。

​
データフィルタリングのエラー

エラー: invalid group name: GroupName原因: 指定されたグループ名は組織内に存在しません。解決策:
  • グループ名の綴りを再確認する
  • チーム設定でそのグループが存在するか確認する
  • チームのダッシュボードに表示されている表記どおりのグループ名を使用する
エラー: invalid timestamp format原因: タイムスタンプが正しい RFC 3339 形式ではありません。解決策: 正しいタイムスタンプ形式を使用してください:
2023-01-01T00:00:00Z
有効な例:
  • 2024-01-01T00:00:00Z
  • 2024-12-31T23:59:59Z
  • 2024-06-15T12:30:45Z
エラー: Cannot use both group_name and emails parameters原因: Cascade の Analytics リクエストで group_name と emails の両方のパラメータが指定されています。解決策: group_name と emails のいずれか一方のみを使用してください（同時指定は不可）:無効:
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
有効:
{
  "group_name": "engineering"
}
または:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
レート制限

エラー: 429 Too Many Requests原因: API のレート制限を超過しています。解決策:
  • 追加のリクエストを送信する前に時間を置く
  • クライアントで指数バックオフを実装する
  • 可能であれば複数のクエリを 1 件のリクエストにまとめる
  • より高いレート上限が必要な場合はサポートへお問い合わせください

​
デバッグのコツ

​
1. まずはシンプルに

まずは基本的なクエリから始め、段階的に複雑さを増やしていきましょう: 
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. フィールド名の検証

フィールド名を Available Fields のドキュメントと照らし合わせて再確認してください。

​
3. 集計の互換性を確認する

選択しているフィールドの型が、使用する集計関数と互換性があることを確認してください。

​
4. フィルターを個別にテストする

クエリで期待どおりの結果が返らない場合は、原因を切り分けるために、フィルターを一つずつ解除して確認してください。

​
5. 適切な JSON 形式を使用する

JSON が正しくフォーマットされ、すべての文字列が正しく引用符で囲まれていることを確認してください。

​
サポートの利用

問題が解決しない場合は、次の手順をお試しください。
  1. エラーメッセージをよく確認する - ほとんどのエラーには、解決方法に関する具体的な指示が含まれています
  2. サンプルを確認する - ドキュメントの動作するサンプルと照らし合わせて、クエリの構造を比較します
  3. サポートに連絡する - 具体的なエラーメッセージとクエリ内容を添えて、Windsurf Support にお問い合わせください

​
API バージョンに関する注意事項

API バージョン 1.10.0 以降では、エラー処理と検証が改善されています。旧バージョンをご利用の場合は、より詳しいエラーメッセージを得るためにアップデートをご検討ください。