> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー処理

> Analytics API（アナリティクス API）の一般的なエラーメッセージとデバッグの手引き（認証、クエリ構造、レート制限に関するエラーを含む）

<div id="overview">
  ## 概要
</div>

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

<div id="error-response-format">
  ## エラーレスポンスの形式
</div>

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

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

<div id="common-errors">
  ## よくある誤り
</div>

<div id="authentication-errors">
  ### 認証エラー
</div>

<AccordionGroup>
  <Accordion title="Invalid service key">
    **エラー:** `Invalid service key`

    **原因:** 提供されたサービスキーが無効であるか、失効しています。

    **解決策:**

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

  <Accordion title="Insufficient permissions">
    **エラー:** `Insufficient permissions`

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

    **解決策:**

    * チーム設定でサービスキーの権限を更新する
    * 各エンドポイントごとに必要な権限については [API introduction](/ja/plugins/accounts/api-reference/api-introduction#required-permissions) を参照する
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### クエリ構造のエラー
</div>

<AccordionGroup>
  <Accordion title="selections の不足">
    **エラー:** `at least one field or aggregation is required`

    **原因:** クエリリクエストに selections または 集計 が含まれていません。

    **解決策:** クエリリクエストに少なくとも 1 つの selection を追加します:

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>

  <Accordion title="無効なデータソース">
    **エラー:** `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`
  </Accordion>

  <Accordion title="集計関数の不一致">
    **エラー:** `all selection fields should have an aggregation function, or none of them should`

    **原因:** 一部の selections には集計関数が設定され、他には設定されていません。

    **解決策:** すべての selections に集計関数を追加するか、すべてから削除してください。

    **不正な例:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
      }
    ]
    ```

    **正しい例:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<div id="field-and-aggregation-errors">
  ### フィールドと集計エラー
</div>

<AccordionGroup>
  <Accordion title="無効な集計関数">
    **エラー:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **原因:** 指定されたフィールド型では、その集計関数はサポートされていません。

    **解決策:** 各フィールドで有効な集計関数は、[Available Fields](/ja/plugins/accounts/api-reference/custom-analytics#available-fields) を参照してください。文字列フィールドは通常、`COUNT` と `UNSPECIFIED` のみをサポートします。
  </Accordion>

  <Accordion title="distinct フィールドの集計">
    **エラー:** `tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]`

    **原因:** "distinct\_\*" パターンのフィールドは、aggregations セクションでは使用できません。

    **解決策:** 提案された代替フィールドで集計してください:

    **無効:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "distinct_developer_days",
        "name": "distinct_developer_days"
      }
    ]
    ```

    **有効:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "api_key",
        "name": "api_key"
      },
      {
        "field": "date",
        "name": "date"
      }
    ]
    ```
  </Accordion>

  <Accordion title="重複したフィールドエイリアス">
    **エラー:** `duplicate field alias for selection/aggregation: num_acceptances`

    **原因:** 複数の selections または集計で同じ name が指定されています。

    **解決策:** すべてのフィールドエイリアスが一意になるようにしてください。name が指定されていない場合、デフォルトは `{aggregation_function}_{field_name}` です。
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### データフィルタリングのエラー
</div>

<AccordionGroup>
  <Accordion title="無効なグループ名">
    **エラー:** `invalid group name: GroupName`

    **原因:** 指定されたグループ名は組織内に存在しません。

    **解決策:**

    * グループ名のスペルを再確認する
    * チーム設定で当該グループの有無を確認する
    * チームのダッシュボードに表示される表記どおりのグループ名を使用する
  </Accordion>

  <Accordion title="無効なタイムスタンプ形式">
    **エラー:** `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`
  </Accordion>

  <Accordion title="競合するフィルター">
    **エラー:** `Cannot use both group_name and emails parameters`

    **原因:** Cascade の Analytics リクエストで `group_name` と `emails` の両方のパラメータが指定されました。

    **解決策:** `group_name` か `emails` のどちらか一方のみを使用し、両方は使用しないでください:

    **無効:**

    ```json theme={null}
    {
      "group_name": "engineering",
      "emails": ["user@example.com"]
    }
    ```

    **有効:**

    ```json theme={null}
    {
      "group_name": "engineering"
    }
    ```

    **または:**

    ```json theme={null}
    {
      "emails": ["user@example.com", "user2@example.com"]
    }
    ```
  </Accordion>
</AccordionGroup>

<div id="rate-limiting">
  ## レート制限
</div>

<AccordionGroup>
  <Accordion title="レート制限を超えました">
    **エラー:** `429 Too Many Requests`

    **原因:** API のレート制限を超過しています。

    **解決策:**

    * 追加のリクエストを送信する前に時間をおく
    * クライアントで指数バックオフを実装する
    * 可能であれば複数のクエリを1つのリクエストにまとめる (バッチ化)
    * より高いレート上限が必要な場合はサポートに問い合わせる
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## デバッグのコツ
</div>

<div id="1-start-simple">
  ### 1. まずはシンプルに
</div>

基本的なクエリから始め、段階的に複雑さを増やしていきましょう。

```json theme={null}
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}
```

<div id="2-validate-field-names">
  ### 2. フィールド名を確認する
</div>

フィールド名を [Available Fields](/ja/plugins/accounts/api-reference/custom-analytics#available-fields) のドキュメントと照らし合わせて再確認してください。

<div id="3-check-aggregation-compatibility">
  ### 3. 集計の互換性を確認する
</div>

選択しているフィールド型に、使用する集計関数が対応していることを確認してください。

<div id="4-test-filters-separately">
  ### 4. フィルターを個別にテストする
</div>

クエリが期待どおりの結果を返さない場合は、問題の切り分けのためにフィルターを一つずつ外して試してください。

<div id="5-use-proper-json-formatting">
  ### 5. 正しいJSON形式を使用する
</div>

JSONが正しく整形され、すべての文字列が適切に引用符で囲まれていることを確認してください。

<div id="getting-help">
  ## ヘルプを得る
</div>

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

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

<div id="api-version-notes">
  ## API バージョンに関する注意事項
</div>

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