Gemini FAILED_PRECONDITION 报错排查

调用 Gemini API 时收到下面这段响应：

hljs json复制
{
  "error": {
    "code": 400,
    "message": "User location is not supported for the API use.",
    "status": "FAILED_PRECONDITION"
  }
}

FAILED_PRECONDITION 是 Gemini API 的一类 400 错误，Google 的错误代码说明把它解释为“某个前提条件未满足（例如结算被停用）”，请求本身的格式没有问题。消息写着 “User location is not supported for the API use.” 时，最常见的原因是请求来自 Gemini API 和 Google AI Studio 不提供服务的国家或地区；另一类是账号或项目的前提没满足，比如项目没有设置结算、Google 账号没有完成年龄验证。截至 2026 年 9 月 30 日，中国大陆、香港、澳门和俄罗斯都不在 Google 公布的适用区域列表里，重试或换模型都不会让这条报错消失。

“User location is not supported for the API use.” 的五种来源

这条报错只说明当前请求不满足使用前提，排查时要先确定是哪一个前提：所在地区、项目结算、账号资格，还是发出请求的机器并不在你以为的位置。

不要用 VPN、代理或不真实的账号资料去“伪装”所在地。Google 的适用区域页面要求查看服务条款了解完整的使用要求；能不能用，取决于你和你的用户实际所在的地方。

先拿到完整的错误响应

判断原因要看响应体里 message 字段的原文，而 SDK 或上层工具打印的异常有时只剩状态码，所以第一步是在出错的那台机器上把完整响应拿出来。本机和服务器的结果可能不同，在哪里报错就在哪里测。

用 curl 直接请求，MODEL 换成你代码里用的模型 ID，key 从环境变量读取：

hljs bash复制
curl -s -w "\nHTTP %{http_code}\n" \
  "https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"ping"}]}]}'

用 Python 的 google-genai SDK 时，捕获 APIError 并把三个字段都打出来：

hljs python复制
from google import genai
from google.genai import errors

client = genai.Client()  # 读取环境变量 GEMINI_API_KEY

try:
    client.models.generate_content(model="你的模型 ID", contents="ping")
except errors.APIError as e:
    print(e.code, e.status)
    print(e.message)

读结果时按这个顺序看：

1. code 是 400、status 是 FAILED_PRECONDITION，message 含 “User location is not supported”：按下文的地区、账号、部署位置三节排查。
2. message 提到 billing：先看项目结算。
3. code 是 403、status 是 PERMISSION_DENIED，或 429、402：这是另一类问题，见后文的状态码对照表。

所在地区不在 Gemini API 适用区域内

如果你或发出请求的服务器位于适用区域列表之外，Gemini API 会拒绝请求，改代码或换 key 都不会改变结果。

Google 的适用区域页面列出了 Gemini API 和 Google AI Studio 提供服务的国家和地区。这份列表最近一次更新是 2026 年 4 月 28 日；截至 2026 年 9 月 30 日，中国大陆、香港、澳门和俄罗斯不在列表中，日本和韩国在列表中。列表会调整，判断前看一眼页面上的更新日期。

对列表外的用户，Google 在同一页面给出的官方建议是“尝试使用 Gemini Enterprise Agent Platform 中的 Gemini API”。它和 AI Studio 的 key 不是同一套开通方式，有自己的账号、计费和可用范围，迁移前按它的文档确认你所在地能否开通。

所在地区不受支持时，开通结算也不会让它变成适用区域。这种情况下不必继续在 AI Studio 里反复换项目、换 key。

项目结算或账号前提没满足

Google 对 400 FAILED_PRECONDITION 给出的处理建议是“检查项目结算状态或账号前提条件”，结算被停用是官方举的例子。Stack Overflow 上 2024 年的报告里，这条报错还有一个更直白的旧写法：“User location is not supported for the API use without a billing account linked”，说明项目没有关联结算账号。

结算挂在项目上，不是挂在单个 key 上。key 属于哪个项目，就给哪个项目设置结算；Google 的速率限制同样按项目计算，不按 key 计算。按 Gemini API 结算说明，截至 2026 年 9 月 30 日，从免费层升级的步骤是：

1. 在 Google AI Studio 打开 API keys 或 Projects 页面，找到 key 所属的免费层项目。
2. 点 Set up billing，选择国家或地区，填写联系方式和付款信息。
3. 选择已有的结算账号，或新建一个。
4. 完成预付，最低购买额为 $5。

有两点容易混淆：

• 预付余额降到 $0 时，关联到该结算账号的所有项目的 key 会同时停用，报错是 HTTP 402 Payment Required，而不是 400。
• 免费层并不只在少数地区开放：Google 在结算说明里写明，免费层和付费层在许多地区都提供，包括欧洲经济区、英国和瑞士。身处适用区域内却报这个错时，除了结算，也要看下一节的年龄验证。

免费层各模型的额度与超限后的选择，见 Gemini API 免费额度与限制：哪些模型免费，超限怎么办。

Google 账号未满足年龄或验证要求

Google AI Studio 的适用区域说明列出三个会被挡在门外的原因，其中两个与地区无关：账号未达到 18 岁的最低年龄，或者账号可能已经有权限，但还没在 Google 账号中完成年龄验证。

判断方法很直接：用创建 key 的那个账号登录 AI Studio。如果被带到“适用区域”页面，而你所在地区在列表内，就去 Google 账号里完成年龄验证，再重新创建或测试 key。账号资料要如实填写；未满 18 岁的账号无法使用这项服务。

Google 帮助社区 2026 年 2 月 16 日有一个帖子，报告新建的 key 返回 400，而同一用户的旧 key 仍然正常。遇到这种情况，先对比两个 key 分别属于哪个项目、由哪个账号创建、项目是否设置了结算，从这几项里找差异。

代码部署在服务器或云函数上

Google 的公开文档没有说明“user location”具体如何判定，所以部署到服务器以后，先确认请求究竟从哪台机器发出。本机调用正常而部署后报错，或者只有某个区域的实例报错，都指向部署位置。

排查时看这几处：

• 云函数、容器服务或虚拟机的部署区域（控制台里通常叫 region 或“地域”）。
• 同一服务是否在多个区域有实例，报错是否只来自其中一个。
• 请求是否经过了另一台服务器转发，真正调用 Gemini 的是哪一台。

如果你的服务本来就面向适用区域内的用户，只是部署时选了列表外的区域（例如香港），把调用 Gemini 的后端迁到列表内、你有权运营服务的区域即可。前提是你的服务和用户本身符合 Google 的条款：身处列表外的人借一台海外服务器发起请求，只是换了一种形式伪装所在地。

Gemini CLI、Antigravity 与第三方应用里的同一条报错

在 Gemini CLI 里，这条报错会被整句转成大写，显示为 [API ERROR: USER LOCATION IS NOT SUPPORTED FOR THE API USE. (STATUS: FAILED_PRECONDITION)]，GitHub 上的 gemini-cli 第 1993 号 issue（2025 年 6 月 26 日）记录的就是这种形式。Antigravity 用户在 Google AI 开发者论坛（2026 年 4 月 21 日，mac 环境）和 Reddit 上报告的，则是 “HTTP 400 FAILED_PRECONDITION”。这些工具背后调用的是同一个 Gemini API，排查顺序不变：所在地区、账号年龄验证、所用项目的结算状态。

在 Make 等自动化平台或别人开发的应用里看到这段 JSON 时，请求可能由应用方的服务器发出。你在自己电脑上改设置影响不到那台服务器，把完整报错、发生时间和你用的 key 所属项目（不要发 key 本身）交给应用开发者处理。

它不是额度错误：400、403、429、402 的区别

FAILED_PRECONDITION 不会因为等待或重试而消失，把它放进自动重试逻辑只会重复失败。下表按 Google 的错误代码说明和结算说明整理，截至 2026 年 9 月 30 日：

如果拿到的是 403，排查方法见AI Studio permission denied 怎么解决。

联系支持前的检查清单

以下几项都确认过仍然报错，再去求助，附上的信息也能让对方直接定位：

1. 保存完整响应体（code、status、message 三个字段）和发生时间，注明时区。
2. 写下发出请求的机器所在国家或地区，或云服务的部署区域，并对照适用区域列表。
3. 确认 key 所属的项目，在 AI Studio 里查看该项目是否设置了结算、预付余额是否为 $0。
4. 用创建 key 的账号登录 AI Studio，确认没有被带到“适用区域”页面。
5. 新 key 报错、旧 key 正常时，对比两个 key 的项目、创建账号和结算状态。
6. 用 Gemini CLI 或 Antigravity 时记下工具版本；用第三方应用时先联系应用开发者。
7. 在 Google AI 开发者论坛发帖（Gemini CLI 的问题提到 gemini-cli 的 GitHub issues），附上以上信息，隐去 API key。

论坛里也有 2026 年 6 月 26 日的帖子，报告网络环境没有变化、这条报错却突然出现。碰到这类情况，前面 1 到 5 项的记录就是最有用的材料。

常见问题

换一个新的 API key 能解决吗？

同一个项目里换 key 通常没用。结算、速率限制都按项目计算，地区和年龄条件则取决于你所在的地方和账号本身，新 key 不改变其中任何一项。只有旧 key 所在的项目确实缺了结算，而新 key 建在已设置结算的项目里时，结果才会不同。

已经设置结算，为什么还报这个错？

先确认结算设在了 key 所属的那个项目上，而不是账号下的另一个项目；再确认预付余额没有降到 $0（那时报错是 402）。这两项都没问题，就回到地区和账号年龄验证两项：所在地区不在适用区域内时，结算不能让它变得可用。

用 VPN 或代理换个出口可以吗？

不要这样做。适用区域是 Google 对服务提供范围的规定，用 VPN、代理或不真实的账号资料改变表面上的所在地，不在 Google 给出的处理方式之内；适用区域页面也提示用户按服务条款了解完整的使用要求。所在地区不受支持时，官方给出的路线是 Gemini Enterprise Agent Platform 中的 Gemini API。