--- title: "排查 Cato API 调用" slug: "troubleshooting-cato-api-calls" updated: 2026-07-30T03:23:24Z published: 2026-07-30T03:23:24Z canonical: "knowledge.catonetworks.com/troubleshooting-cato-api-calls" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.catonetworks.com/llms.txt > Use this file to discover all available pages before exploring further. # 排查 Cato API 调用 本文章提供一些解决常见错误的建议,这些错误可能在使用 API 工具和软件运行 Cato 的 API 查询时出现。 例如,Altair 和 Postman。 不支持与 API 脚本和编码相关的问题。 ## 必需的 API 参数 这些是您必须在 API 查询中包含的参数。 当从 API 查询中去除可选参数时,将使用默认值。 - accountMetrics 查询 - id - 账户 ID - timeframe - 查询返回数据的时间范围 - groupDevices - 对于多个站点以及具有多个 Sockets 的站点,将分析数据合并到一个 Socket 中(对于布尔值 **true**) - accountSnapshot 查询 - id - 账户 ID ## 常见 GRAPHQL_PARSE_FAILED 错误 本节解释了一些与 Cato GraphQL 架构相关的错误消息常见示例。 ### 消息: 意外的) 查询中有多余的括号。 常常因为没有为参数提供布尔值而导致此错误。 例如,`groupInterfaces: ,` 而不是 `groupInterfaces: true,` ### 消息: 预期名称,发现 <字符> JSON 文件的格式不正确。 消息显示一个与缺少或多余字符相关的字符。 例如,**预期名称,发现 (** 对于参数 `accountSnapshot((id: 42)`。 对此参数的正确格式是 `accountSnapshot(id: 1941)` ### 消息: 预期名称,发现 <无效> 错误消息表明有一个参数值无效。 例如,Cato API 中的 **timeFrame** 参数 (**accountMetrics**) 使用引号隔开的 ISO 8601 日期时间标准,`timeFrame: "last.P1D"` 是正确的,而 `timeFrame: last.P1D` 则会产生此错误。 ## 常见 GRAPH_QL_VALIDATION_FAILED 错误 本节解释了一些与查询参数格式不正确相关的错误消息常见示例。 ### 消息: 预期类型 String !,发现 <数字> 错误消息表明参数有一个无效值,通常与参数格式有关。 例如,**站点 IDs** 参数 (**accountMetrics > 站点**) 是一个字符串,因此您必须为值使用引号,`ids: ["4242"]` 是正确的,`ids:[4242]` 则会产生此错误。 ### 消息: 预期类型 Int !,发现 \"<数字>\" 错误消息表明参数有一个无效值,通常与参数格式有关。 例如,**站点 IDs** 参数 (**accountSnapshot > 站点**) 是一个整数,因此不应为值使用引号,`ids: [2626]` 是正确的,`ids:["2626"]` 则会产生此错误。 ## API 错误消息 本节解释的一些常见错误消息不与 Cato GraphQL 架构或格式特定相关。 ### 消息: 身份验证错误或 403 您账户的 API 密钥出现问题。 建议的解决方案: - 在 Cato 管理应用程序 (**系统 > API 访问管理**) 中,确保: - 您正在使用的 API 密钥仍然有效(存在且未过期) - 如果设置了 **允许来自 IP 的访问** 选项,则 API 客户端从某个特定允许的 IP 地址或范围进行调用 - 确认密钥在 API 查询软件的 HTTP 头设置中配置正确:`x-api-key: <密钥值>`,例如 `x-api-key: abcdef12345` - 若问题继续,生成一个新的 API 密钥并添加到 API 查询软件中 这是一个 API 客户端的有效 HTTP 头示例: ```plaintext POST /api/v1/graphql2 HTTP/2 Host: api.catonetworks.com User-Agent: curl/8.7.1 Accept: */* Content-Type:application/json x-api-key: abcdef123456789 ``` ### 消息:当选择多个站点时无法分离设备(组设备 = false) 当查询包含多个站点时,**groupDevices** 参数(**accountMetrics**) 的值必须为 **true**。 ## 转换 API 分析数据 Cato API 返回的数据为字节。 要将数据转换为更大单位(例如 MB 或 GB),您需要除以 1024 的指数值:MB 用 10242,GB 用 10243。 例如,要将 536,870,912,000 字节转换为 GB,请除以 10243,显示为 500GB 的数据。