​
概要

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 または集計で同じ name が指定されています。解決策: すべてのフィールドエイリアスが一意になるようにしてください。name が指定されていない場合、デフォルトは {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 以降では、エラー処理と検証が改善されています。旧バージョンをご利用の場合は、より詳細なエラーメッセージを得るためにアップデートをご検討ください。