> ## 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 常见错误消息与调试技巧，包括身份验证、查询结构以及速率限制相关错误。

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

Analytics 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`

    **原因：** 该服务密钥不具备你正在调用的 endpoint 所需的权限。

    **解决方案：**

    * 在团队设置中更新服务密钥的权限
    * 参考 [API 介绍](/zh/windsurf/accounts/api-reference/api-introduction#required-permissions) 以了解每个 endpoint 所需的具体权限
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### 查询结构错误
</div>

<AccordionGroup>
  <Accordion title="缺少 selections">
    **错误：** `at least one field or aggregation is required`

    **原因：** 查询请求未包含任何 selections 或 aggregations。

    **解决方案：** 在查询请求中至少添加一个 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](/zh/windsurf/accounts/api-reference/custom-analytics#available-fields) 部分，了解各字段支持的聚合函数。字符串字段通常只支持 `COUNT` 和 `UNSPECIFIED`。
  </Accordion>

  <Accordion title="去重字段聚合">
    **错误：** `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 或 aggregations 使用了相同的名称。

    **解决方案：** 确保所有字段别名唯一。请注意，若未指定名称，默认格式为 `{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 限制。

    **解决方案：**

    * 等待一段时间后再发起更多请求
    * 在客户端实现指数退避重试
    * 在可行时将多个查询合并为单个请求
    * 如需更高的限额，请联系支持
  </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](/zh/windsurf/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 及更高版本中，错误处理和校验已得到改进。如果你使用的是较早的版本，建议更新以获取更详细的错误信息。