跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

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

​
错误响应格式

发生错误时，API 会返回包含说明性消息的错误响应： 
{
  "error": "Error message describing what went wrong"
}

​
常见错误

​
身份验证错误

错误： Invalid service key原因： 你提供的服务密钥无效或已被撤销。解决方案：
  • 确认你的服务密钥是否正确
  • 检查该服务密钥是否已被撤销
  • 如有需要，生成新的服务密钥
错误： Insufficient permissions原因： 该服务密钥没有你正在调用的端点所需的权限。解决方案：
  • 在团队设置中更新服务密钥的权限
  • 参阅 API 简介，了解每个端点所需的具体权限

​
查询结构错误

错误： at least one field or aggregation is required原因： 查询请求中未包含任何选择字段或聚合。解决方案： 在你的查询请求中至少添加一个选择字段：
"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": [
  {
    "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原因： 指定字段类型不支持该聚合函数。解决方案： 查看可用字段部分，确认每个字段支持哪些聚合函数。字符串字段通常只支持 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原因： 多个选择字段或聚合项使用了相同的名称。解决方案： 确保所有字段别名都是唯一的。请注意，如果未指定名称，默认会使用 {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. 验证字段名称

请对照可用字段文档，仔细核对字段名称。

​
3. 检查聚合兼容性

确保你使用的聚合函数与所选字段的类型兼容。

​
4. 逐一测试筛选条件

如果你的查询没有返回预期结果，尝试逐个移除筛选条件，以便定位问题。

​
5. 使用正确的 JSON 格式

确保你的 JSON 格式正确，并且所有字符串都使用正确的引号包裹。

​
获取帮助

如果你仍然遇到问题：
  1. 仔细查看错误消息 - 大多数错误都会提供有关如何修复问题的具体指引
  2. 查看示例 - 将你的查询结构与文档中的有效示例进行对比
  3. 联系支持团队 - 带上你的具体错误消息和查询，联系 Devin Desktop Support

​
API 版本说明

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