本页介绍使用 AI Gateway 时的常见问题。有关提供商特定的故障排除,请参阅相关提供商文档。
如果你收到来自 AI 提供商的身份验证错误,说明 AI Gateway 未将有效凭据传递到上游。请检查以下内容:
-
验证标头位置:对于供应商原生端点,请将 Cloudflare token 放入
cf-aig-authorization。按照 AI Gateway 针对相应供应商和端点识别的格式提供供应商凭据。例如,Anthropic Messages 需要x-api-key,而 OpenAI 使用Authorization: Bearer。 -
根据端点类型检查配置:
- 提供商专用端点:确认请求 URL 包含提供商路径(例如
/google-vertex-ai/或/openai/)。AI Gateway 使用此路径识别提供商并应用正确的已存储凭据。 - 统一
/compat/chat/completions端点:确认你的model名称以提供商前缀开头(例如google-vertex-ai/google/gemini-2.5-flash或openai/gpt-4o)。AI Gateway 使用此前缀路由请求并选择正确的已存储凭据。
- 提供商专用端点:确认请求 URL 包含提供商路径(例如
-
验证 BYOK 密钥选择:如果为某个提供商配置了多个密钥,请确保:
- 你使用的是别名为
default的密钥,或 - 你包含了带有正确别名名称的
cf-aig-byok-alias标头
- 你使用的是别名为
-
验证 BYOK 配置:如果使用 BYOK,请在仪表板中确认凭据已正确保存。
有关提供商特定的身份验证问题:
如果 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 故障排除。
- 直接向提供商验证你的 API 密钥或凭据是否有效
- 检查提供商的状态页面是否有中断
- 查看 AI Gateway 日志 获取详细错误信息
- 验证 gateway 已启用缓存
- 检查请求方法和内容类型是否可缓存
- 流式响应默认不会被缓存