跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

故障排除

最后更新 查看 MarkdownAgent 设置

本页介绍使用 AI Gateway 时的常见问题。有关提供商特定的故障排除,请参阅相关提供商文档。

身份验证错误

401 或未认证错误

如果你收到来自 AI 提供商的身份验证错误,说明 AI Gateway 未将有效凭据传递到上游。请检查以下内容:

  1. 验证标头位置:对于供应商原生端点,请将 Cloudflare token 放入 cf-aig-authorization。按照 AI Gateway 针对相应供应商和端点识别的格式提供供应商凭据。例如,Anthropic Messages 需要 x-api-key,而 OpenAI 使用 Authorization: Bearer。

  2. 根据端点类型检查配置:

    • 提供商专用端点:确认请求 URL 包含提供商路径(例如 /google-vertex-ai/ 或 /openai/)。AI Gateway 使用此路径识别提供商并应用正确的已存储凭据。
    • 统一 /compat/chat/completions 端点:确认你的 model 名称以提供商前缀开头(例如 google-vertex-ai/google/gemini-2.5-flash 或 openai/gpt-4o)。AI Gateway 使用此前缀路由请求并选择正确的已存储凭据。
  3. 验证 BYOK 密钥选择:如果为某个提供商配置了多个密钥,请确保:

    • 你使用的是别名为 default 的密钥,或
    • 你包含了带有正确别名名称的 cf-aig-byok-alias 标头
  4. 验证 BYOK 配置:如果使用 BYOK,请在仪表板中确认凭据已正确保存。

有关提供商特定的身份验证问题:

400:需要供应商凭据(2044)

如果 AI Gateway 找不到适用的供应商凭据,且 Unified Billing 回退已被阻止,则会返回 HTTP 400、错误代码 2044,并显示消息 Customer-provided provider credentials are required for this request。

当网关启用了 Require provider credentials,或请求包含 cf-aig-no-wholesale: true 时,回退会被阻止。请求中提供的凭据或适用的已存储 BYOK 密钥均可满足此要求。

要解决此错误:

  • 使用已识别的凭据格式提供供应商密钥。
  • 对于 Anthropic Messages(/anthropic/v1/messages),请发送 x-api-key: <PROVIDER_API_KEY>。AI Gateway 不会将此端点上的 Authorization: Bearer 识别为供应商凭据。
  • 如果使用已存储的 BYOK 密钥,请验证网关身份验证和密钥别名。使用 default,或在供应商原生请求中通过 cf-aig-byok-alias 选择适用的别名。

DLP 问题

有关 DLP 未触发或意外阻止等数据丢失防护问题的故障排除,请参阅 DLP 故障排除。

请求失败

请求超时

  • 检查上游提供商是否遇到问题
  • 考虑使用带回退的动态路由处理临时故障
  • 审查你的速率限制配置

请求返回来自提供商的错误

  • 直接向提供商验证你的 API 密钥或凭据是否有效
  • 检查提供商的状态页面是否有中断
  • 查看 AI Gateway 日志 获取详细错误信息

缓存问题

请求未被缓存

  • 验证 gateway 已启用缓存
  • 检查请求方法和内容类型是否可缓存
  • 流式响应默认不会被缓存

意外的缓存命中或未命中

这篇文档对您有帮助吗?