> ## 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.

# 错误处理

> 分析 API 中与身份验证、查询结构和速率限制相关的常见错误消息及调试提示。

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

分析 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="无效的服务密钥">
    **错误：** `Invalid service key`

    **原因：** 你提供的服务密钥无效或已被撤销。

    **解决方案：**

    * 确认你的服务密钥是否正确
    * 检查该服务密钥是否已被撤销
    * 如有需要，生成新的服务密钥
  </Accordion>

  <Accordion title="权限不足">
    **错误：** `Insufficient permissions`

    **原因：** 该服务密钥没有你正在调用的端点所需的权限。

    **解决方案：**

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

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

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

    **原因：** 查询请求中未包含任何选择字段或聚合。

    **解决方案：** 在你的查询请求中至少添加一个选择字段：

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

    **原因：** 某些选择字段设置了聚合函数，而其他选择字段没有设置。

    **解决方案：** 要么为所有选择字段添加聚合函数，要么全部移除：

    **无效：**

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

    **原因：** 指定字段类型不支持该聚合函数。

    **解决方案：** 查看[可用字段](/zh/desktop/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`

    **原因：** 多个选择字段或聚合项使用了相同的名称。

    **解决方案：** 确保所有字段别名都是唯一的。请注意，如果未指定名称，默认会使用 `{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>

请对照[可用字段](/zh/desktop/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. **联系支持团队** - 带上你的具体错误消息和查询，联系 [Devin Desktop Support](https://windsurf.com/support)

<div id="api-version-notes">
  ## API 版本说明
</div>

API 1.10.0 及更高版本改进了错误处理和验证功能。如果你使用的是较早版本，建议更新，以获得更详细的错误信息。