本页面记录了 Spectrum API 返回的错误代码，以及帮助进行故障排除的推荐修复方法。
Spectrum API 错误遵循标准的 Cloudflare v4 错误封装格式。响应正文包含一个带有 code 和 message 字段的 errors 数组：
{
"errors": [
{
"code": 11044,
"message": "No matching routes in the specified virtual network."
}
],
"messages": [],
"success": false,
"result": null
}在请求处理期间发生意外错误。响应不包含诊断详细信息。如果您联系 Cloudflare 支持团队，请提供响应中的 Ray ID，以便定位原始错误。
HTTP 503 表示依赖服务（如 DNS 或 IP 地址管理）暂时不可用。HTTP 500 表示任何其他内部错误。
请求正文包含 API 无法识别的字段。此错误仅针对随用随付 (Pay-as-you-go) 账户上的应用程序返回。Enterprise 应用程序会静默忽略未知字段。
在创建或更新 Spectrum 应用程序时，随用随付账户仅限于使用 protocol、dns 和 origin_direct。一个常见原因是，没有 Spectrum 授权的账户发送了完整的 Spectrum 配置 —— 任何在这三个字段之外的字段都会被拒绝。
解决方法： 要使用完整的 Spectrum 配置 API，请联系您的客户团队将 Spectrum 作为付费附加组件启用。否则，请从请求中删除除 protocol、dns 和 origin_direct 之外的任何字段。
除非另有说明，这些错误均作为 HTTP 400 返回。
请求必须提供 origin_direct 或 origin_dns 中的一个，且只能提供一个。同时提供两者或均不提供都会触发此错误。
origin_dns 配置验证失败。常见原因：
origin_dns.name不是有效的域名。- 提供了一个非 SRV 的
origin_dns.type，但没有origin_port。 origin_dns.ttl超出了允许的范围。
提供的一个或多个源站地址无效。
常见原因：
- 未加方括号的 IPv6 源站： 在
origin_direct中，IPv6 地址必须用方括号括起来，例如tcp://[2001:db8::1]:443。如果没有方括号，地址中的冒号会使解析变得不明确。 - 源站 IP 未通过访问控制验证： 源站 IP 可能未能通过内部访问控制检查。请验证 IP 是否有效并属于允许的范围。
DNS 类型必须与边缘 IP 分配模式匹配。动态边缘 IP 需要 type: "CNAME"。静态 (BYOIP) 边缘 IP 需要 type: "ADDRESS"。如果您在更新现有应用程序时尝试更改 DNS 类型，也会返回此错误。
未为该账户启用 FTP 流量类型。作为 HTTP 403 返回。
解决方法： 请联系您的客户团队以启用 FTP 支持。
未为该账户启用 edge_ips 功能 (BYOIP)。作为 HTTP 403 返回。
解决方法： 请联系您的客户团队以为该账户启用 BYOIP。
经过身份验证的账户无权使用提供的 edge_ips。
常见原因：
- API 令牌缺乏 IP 前缀权限： 范围限定为 Spectrum 的 API 令牌可能不具备 BYOIP 验证所需的 IP 前缀权限。请使用 Global API Key，或将 Account > IP Prefixes 权限添加到 API 令牌中。
- BYOIP 前缀未分配给账户： 在分配之前，请验证 BYOIP 前缀是否已分配给发出请求的账户。
请求将 argo_smart_routing 设置为 true，但未为该账户启用 Argo Smart Routing。作为 HTTP 403 返回。
解决方法： 请联系您的客户团队以为该账户启用 Argo Smart Routing。
提供的一个或多个 edge_ips 已经被另一个区域 (zone) 使用。
常见原因：请求的边缘 IP 可能被已删除区域上的旧有 Spectrum 应用程序占用。请联系 Cloudflare 支持团队清理该孤儿应用程序。
随用随付账户限制每个协议只能创建一个应用程序。如果您需要在同一协议上使用多个应用程序，请联系您的客户团队将 Spectrum 作为付费附加组件启用。
用作源站的 DNS 记录或负载均衡器位于不同的区域或不允许的区域上。
解决方法： 将源站 DNS 记录或负载均衡器移动到同一区域，或者改用带有 IP 地址的 origin_direct。
在使用虚拟网络源站验证应用程序时，POST /zones/:zone/spectrum/apps 和 PATCH /zones/:zone/spectrum/apps/:id 会返回以下代码。
在使用了 origin_dns 的请求上设置了 virtual_network_id。虚拟网络源站仅支持基于 IP 的源站。
解决方法： 用 origin_direct 替换 origin_dns，并提供虚拟网络路由到的私有 IP 和单一端口。
origin_direct 包含多个地址。虚拟网络源站必须解析为单一的私有 IP 和端口。
解决方法： 将 origin_direct 减少为 tcp://<IP>:<PORT> 或 udp://<IP>:<PORT> 形式的单一项。
请求包含端口范围，无论是在 origin_port 还是在 origin_direct 地址中。虚拟网络源站不支持端口范围。
解决方法： 使用单一端口而不是范围。如果您需要暴露多个端口，请为每个端口创建一个单独的 Spectrum 应用程序。
IP 和 virtual_network_id 的组合与指定虚拟网络中的任何路由都不匹配。这涵盖了两种情况：虚拟网络不存在，或者 IP 在您指定的虚拟网络内不可路由。
解决方法：
- 确认
virtual_network_id与您账户中的虚拟网络匹配。您可以使用 List virtual networks 端点列出虚拟网络。 - 确认源站 IP 位于附加到该虚拟网络的路由内。您可以使用 List network routes 端点列出路由。
- 如果没有匹配的路由，请按照连接 IP/CIDR 添加一个。
virtual_network_id 不是有效的 UUID。
解决方法： 提供一个 UUID。虚拟网络 ID 由 List virtual networks 端点在每个条目的 id 字段中返回。
该区域已分配其配额中所有可用的 IPv4 地址。
解决方法： 将应用程序整合到更少的 IP 上（多个应用可以在不同端口上共享一个主机名），购买额外的 Cloudflare 托管 IP，或接入 BYOIP。
请求的协议对于该区域不可用。错误消息包括针对所请求协议不允许的特定边缘端口。
已经存在具有相同 DNS 名称的主机名，但它属于不同的区域。当主机名查找与另一个区域拥有的记录匹配时，在创建或更新应用程序期间可能会发生这种情况。
解决方法：
- 验证您在 API 请求 URL 中使用的是否为正确的区域 ID。
- 为应用程序使用不同的 DNS 名称。
- 如果该 DNS 名称以前在您控制的另一个区域上使用过，请先删除该区域上的应用程序。
- 如果这些都不适用，请联系 Cloudflare 支持团队 —— 主机名可能需要在内部进行清理。