エラー処理

概要

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

エラーレスポンスの形式

エラーが発生すると、API は説明的なメッセージを含むエラーレスポンスを返します。

{
  "error": "何が問題だったかを説明するエラーメッセージ"
}

よくある誤り

認証エラー

Invalid service key

エラー: Invalid service key原因: 提供されたサービスキーが無効であるか、失効しています。解決策:

サービスキーが正しいか確認する
サービスキーが失効していないか確認する
必要に応じて新しいサービスキーを発行する

Insufficient permissions

エラー: Insufficient permissions原因: サービスキーに、呼び出しているエンドポイントに必要な権限が付与されていません。解決策:

チーム設定でサービスキーの権限を更新する
各エンドポイントごとに必要な権限については API introduction を参照する

クエリ構造のエラー

selections の不足

エラー: 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 のみをサポートします。

distinct フィールドの集計

エラー:

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が正しく整形され、すべての文字列が適切に引用符で囲まれていることを確認してください。

ヘルプを得る

問題が引き続き発生する場合は、次をお試しください:

エラーメッセージをよく確認する - 多くのエラーには、解決方法に関する具体的な案内が含まれています
サンプルを見直す - ドキュメントの動作するサンプルとクエリの構造を比較してください
サポートに連絡する - 具体的なエラーメッセージとクエリ内容を添えて、Windsurf Support にお問い合わせください

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

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

はじめに

機能

Cascade (JetBrains)

アカウント

コンテキスト認識

ベストプラクティス

トラブルシューティング

セキュリティ

概要

エラーレスポンスの形式

よくある誤り

認証エラー

クエリ構造のエラー

フィールドと集計エラー

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

レート制限

デバッグのコツ

1. まずはシンプルに

2. フィールド名を確認する

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

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

5. 正しいJSON形式を使用する

ヘルプを得る

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

​概要

​エラーレスポンスの形式

​よくある誤り

​認証エラー

​クエリ構造のエラー

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

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

​レート制限

​デバッグのコツ

​1. まずはシンプルに

​2. フィールド名を確認する

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

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

​5. 正しいJSON形式を使用する

​ヘルプを得る

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

概要

エラーレスポンスの形式

よくある誤り

認証エラー

クエリ構造のエラー

フィールドと集計エラー

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

レート制限

デバッグのコツ

1. まずはシンプルに

2. フィールド名を確認する

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

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

5. 正しいJSON形式を使用する

ヘルプを得る

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