Gemini API 提示 User location is not supported：先分清 400 与 403

看到 User location is not supported for the API use 时，先不要继续重试，也不要只凭这句 message 认定是“IP 被封”。真正有诊断价值的是同一次响应里的三个字段：HTTP code、status 和完整 message。

• 400 + FAILED_PRECONDITION：Google 当前排障文档把这一类情况与“免费层尚未在请求所在地区推出、且项目未启用结算”关联。优先核对地区资格和 API key 所属项目的结算状态。
• 403 + PERMISSION_DENIED：优先检查 API key、身份验证和资源权限，不要沿用 400 的结算结论。

400 和 403 都是客户端侧错误，不属于适合自动重试的瞬时故障。换模型、增加重试次数或重新部署同一配置，通常只会重复失败。

第一步：保存完整错误，不要只截取 message

请从服务端日志、SDK 异常对象或原始 HTTP 响应中保存以下信息：

json
{
  "http_code": 400,
  "status": "FAILED_PRECONDITION",
  "message": "User location is not supported for the API use."
}

示例只用于展示需要记录的字段；请以你实际收到的响应为准。日志中可以保留时间、请求 endpoint、模型名、部署环境和 Google Cloud project ID，但不要记录完整 API key、Authorization header 或用户数据。

如果你只能看到封装后的中文提示，先让调用层输出状态码和结构化错误。以 JavaScript 的 fetch 为例：

js
const response = await fetch(endpoint, requestOptions);
const body = await response.json().catch(() => null);

console.error({
  httpCode: response.status,
  status: body?.error?.status,
  message: body?.error?.message,
  endpoint: new URL(endpoint).origin,
});

不要把 requestOptions.headers 整体写入日志；其中往往包含凭据。

400 与 403 应该走不同的排障分支

Google 当前建议只对 429、408 和 5xx 等可能短暂出现的错误采用退避重试。对 400 或 403，应先修正前置条件或权限。

如果是 400 FAILED_PRECONDITION

1. 先确认你使用的是哪个产品

这里讨论的是 Gemini Developer API，以及在 Google AI Studio 中创建和管理相关 API key、project 与结算的流程。不要把下面几个产品面混为一谈：

• Google AI Studio 是开发与项目配置入口之一；API key 仍归属于一个 project。
• Gemini Developer API 是当前请求所在的 API 产品面。
• Colab 有单独的明确规则：地区限制按 Colab 实例所在区域应用。这个规则不能外推到普通 REST、SDK、VPS、Serverless 或移动端请求。
• Gemini Enterprise Agent Platform 是独立的 Google Cloud 产品路径，有自己的资格、账单、IAM、区域和数据处理约束，不是把 Developer API URL 换一下就能迁移。

先记录实际 endpoint、SDK 包名和版本、key 的来源，以及应用究竟运行在本机、Colab、云函数、容器还是共享主机。产品面没确认，后面的判断很容易错位。

2. 核对当前官方适用地区

Gemini API 和 Google AI Studio 只在官方页面列出的国家和地区提供。以 2026-08-22 的官方简体中文页面为准，列表中可见日本、新加坡、台湾和美国，未观察到中国、香港或澳门。名单会变化，也不能据此推断其他 Gemini 产品的可用范围，因此排障时应重新查看 Google AI Studio 和 Gemini API 适用地区。

如果用户、应用或服务实际位于未支持地区，就不存在一个可以在本文中承诺的 Developer API 配置修复。Google 的附加条款要求只在 available region 内访问服务或向用户提供 API 客户端；VPN、代理、反向代理、位置欺骗、虚假身份或账单资料都不是本文建议的解决方案。

3. 找到 API key 所属 project，并检查结算

API key 没有独立结算开关：它继承所属 project 的层级限制和结算状态，项目内 key 的累计用量也计入该项目及关联的结算账号。因此，“旧 key 可用、新 key 不可用”不能仅凭现象归因于 key 本身；先确认两个 key 是否真的属于同一 project、同一结算状态和同一调用产品。

建议按这个顺序核对：

1. 在 Google AI Studio 确认报错 key 对应的 project ID。
2. 确认应用加载的就是预期 key，部署环境没有仍引用旧 secret 或空值。
3. 查看该 project 是否已按预期关联有效结算账号，以及结算账号、余额和付款状态是否正常。
4. 再次发起一条最小请求，并比较 code、status、message 是否变化。

Google 当前官方排障页对相关 400 FAILED_PRECONDITION 给出的处理方向，是在 Google AI Studio 为项目设置付费方案。这是针对文档所述“免费层地区尚未推出且项目未启用结算”的分支，不代表启用结算可以覆盖所有地区、资格或条款限制，也不能证明你的账号必然恢复。

失败的 400 请求目前不会按使用的 token 收费，但仍会计入配额。这也是停止循环重试的实际理由。

4. 比较本地与部署环境，但不要臆测判定算法

如果本地可用、部署后失败，请做一次受控对照：保持同一个 project、key、endpoint、模型和最小请求体，只改变执行环境，并分别保存完整响应和时间。

同时确认：

• 生产环境是否真的加载了同一 project 的 key；
• 请求是否从预期容器、函数或主机发出，而不是经过未记录的企业出口；
• 服务商对该运行环境标注的区域，与实际网络出口的国家归类是否一致；
• DNS、HTTP 客户端或应用框架是否把请求发到了不同 endpoint。

Google 公开资料目前没有可靠说明普通 Gemini Developer API REST 或 SDK 请求如何综合判定 User location。因此，不能把 IP、账号注册地、手机号、付款方式中的任意一个写成已确认的通用判定信号。

如果你实际位于受支持地区，但多个 Google 产品都把当前设备 IP 识别成错误国家，可以提交 Google 的 IP 问题报告表。该流程不保证单独回复，更新可能超过一个月，也不保证修复 Gemini API；它不是给未支持地区使用的绕过渠道。

如果是 403 PERMISSION_DENIED

403 PERMISSION_DENIED 应先按权限和身份验证问题处理。逐项确认：

1. key 是否复制完整、没有多余空格，也没有被部署平台中的同名变量覆盖；
2. key 是否来自你预期的 project；
3. 当前 endpoint、API 版本和模型是否与调用代码相符；
4. 如果调用调优模型或受权限控制的资源，当前身份是否具备对应访问权；
5. 修正后只做一次最小请求验证，不要让自动重试掩盖原始错误。

官方排障表把 403 PERMISSION_DENIED 与错误 key、权限不足或调优模型身份验证问题关联。它与 400 FAILED_PRECONDITION 的地区和免费层条件是不同分支。若你的 403 同时带有目标英文 message，仍应保留完整响应并向官方支持提供账号级证据，而不是自行断言位置判定机制。

官方支持之外，怎样选择下一步

完成上面的核对后，通常会落到三种结果：

路径 A：地区受支持，且问题属于项目结算或 key 权限

修正 project、billing 或身份验证配置，随后用一条最小请求验证。成功标准不是“页面能打开”，而是 API 返回成功响应，且生产环境使用的仍是预期 project 与 endpoint。

路径 B：实际位于支持地区，但地区归类可能错误

保存部署区域、出口证据、完整错误响应和发生时间；需要时提交 IP 问题报告，并通过 Google 官方支持渠道继续调查。等待期间不要反复创建 key，也不要把 key 交给第三方“检测”。

路径 C：Developer API 当前不覆盖你的地区或使用场景

停止尝试绕过。可以评估 Google 官方地区页指向的 Gemini Enterprise Agent Platform，但要把它当作一次独立产品选型：重新核验组织资格、Cloud billing、IAM、可用区域、endpoint 和数据治理要求。其全球 endpoint 可以提高可用性，但不能控制请求的具体处理区域，也不保证数据驻留。

如果这些条件不合适，就应选择一个明确支持你的地区、部署模式和数据要求的其他服务，而不是把凭据交给不受信任的第三方网关。

最小化证据包：需要求助时一次说清楚

向官方论坛或支持渠道求助前，准备一份不含密钥的最小证据包：

text
发生时间（含时区）：
HTTP code / status / 完整 message：
产品与 endpoint：
SDK 名称及版本：
模型：
project ID（不要提供 API key）：
project 是否启用结算：
执行环境及服务商标注区域：
本地与部署环境是否有差异：
可复现的最小请求步骤：

最后再检查一次：你解决的应当是一个已确认的前置条件或权限问题，而不是靠改变位置、伪造资料或隐藏请求来源让错误暂时消失。对于这条报错，最短的可靠路径始终是：保留完整返回体 → 区分 400/403 → 确认产品和 project → 核对结算、执行环境与官方地区 → 只选择受支持的下一步。

参考资料

• Gemini API 错误排查指南
• Google AI Studio 和 Gemini API 适用地区
• Gemini API 结算说明
• Gemini API 附加服务条款
• Gemini Enterprise Agent Platform 位置说明