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

# エラー処理

> Analytics API でよくあるエラーメッセージと、認証、クエリ構造、レート制限エラーのデバッグのヒント。

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

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

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

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

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

<div id="common-errors">
  ## よくあるエラー
</div>

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

<AccordionGroup>
  <Accordion title="無効なサービスキー">
    **Error:** `Invalid service key`

    **Cause:** 指定されたサービスキーが無効か、失効しています。

    **解決策:**

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

  <Accordion title="権限が不足しています">
    **Error:** `Insufficient permissions`

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

    **解決策:**

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

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

<AccordionGroup>
  <Accordion title="選択項目がありません">
    **Error:** `at least one field or aggregation is required`

    **Cause:** クエリリクエストに選択項目または集計が含まれていません。

    **解決策:** クエリリクエストに少なくとも 1 つの選択項目を追加してください。

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

  <Accordion title="無効なデータソース">
    **Error:** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

    **Cause:** `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="集計関数が混在しています">
    **Error:** `all selection fields should have an aggregation function, or none of them should`

    **Cause:** 集計関数が設定されている選択項目と、設定されていない選択項目が混在しています。

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

    **Invalid:**

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

    **Valid:**

    ```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="無効な集計関数">
    **Error:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

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

    **解決策:** 各フィールドで利用可能な集計関数については、[利用可能なフィールド](/ja/desktop/accounts/api-reference/custom-analytics#available-fields) セクションを確認してください。文字列フィールドで通常利用できるのは `COUNT` と `UNSPECIFIED` のみです。
  </Accordion>

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

    **Cause:** `distinct_*` パターンのフィールドは、集計セクションでは利用できません。

    **解決策:** 集計には、提案されている代替フィールドを利用してください。

    **Invalid:**

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

    **Valid:**

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

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

    **Cause:** 複数の選択または集計で同じ名前が使用されています。

    **解決策:** すべてのフィールドエイリアスが一意であることを確認してください。名前を指定しない場合、デフォルトでは `{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>

フィールド名が正しいか、[利用可能なフィールド](/ja/desktop/accounts/api-reference/custom-analytics#available-fields)のドキュメントで再確認してください。

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

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

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

クエリで期待どおりの結果が返ってこない場合は、フィルターを1つずつ外して、問題を切り分けてみてください。

<div id="5-use-proper-json-formatting">
  ### 5. JSON を適切な形式で記述する
</div>

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

<div id="getting-help">
  ## サポートが必要な場合
</div>

問題が引き続き発生する場合:

1. **エラーメッセージをよく確認してください** - ほとんどのエラーには、問題の対処法に関する具体的な案内が含まれています
2. **使用例を確認してください** - クエリの構造を、ドキュメント内の正常に動作する使用例と比較してください
3. **サポートに連絡してください** - 具体的なエラーメッセージとクエリを添えて、[Devin Desktop Support](https://windsurf.com/support) にお問い合わせください

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

API バージョン 1.10.0 以降では、エラー処理とバリデーションが改善されています。古いバージョンを使用している場合は、より詳細なエラーメッセージを利用するため、更新をご検討ください。