​
概览

Analytics API 会返回详细的错误信息，帮助你调试无效查询。本文介绍常见错误场景及其解决方法。

​
错误响应格式

发生错误时，API 会返回包含详细说明的错误响应： 
{
  "error": "描述出错原因的错误消息"
}

​
常见错误

​
身份验证错误

错误： Invalid service key原因： 提供的服务密钥无效或已被撤销。解决方案：
  • 核对你的服务密钥是否正确
  • 检查服务密钥是否已被撤销
  • 如有需要，生成新的服务密钥
错误： Insufficient permissions原因： 该服务密钥不具备所需的“Teams Read-only”权限。解决方案：
  • 在团队设置中更新服务密钥的权限
  • 确保该服务密钥具有“Teams Read-only”访问权限

​
查询结构错误

错误： at least one field or aggregation is required原因： 查询请求未包含任何 selections 或 aggregations。解决方案： 在查询请求中至少添加一个 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。
错误： 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 或 aggregations 使用了相同的名称。解决方案： 确保所有字段别名唯一。请注意，若未指定名称，默认格式为 {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. 从简单入手

先从基础查询开始，逐步增加复杂度： 
{
  "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 格式规范，且所有字符串都正确加上引号。

​
获取帮助

如果你仍然遇到问题：
  1. 仔细检查错误信息 - 大多数错误都会包含如何解决问题的具体指引
  2. 查看示例 - 将你的查询结构与文档中的可运行示例进行对照
  3. 联系支持 - 附上你的具体错误信息和查询，联系 Windsurf Support

​
API 版本说明

在 API 1.10.0 及更高版本中，错误处理和校验已得到改进。如果你使用的是较早的版本，建议更新以获取更详细的错误信息。