这篇按生产排查手册写，适合已经把 Gemini API 接进后端服务的开发者。目标不是介绍模型能力，而是把错误码、限流、重试、超时、国内访问和多模型降级讲清楚。

1. 错误码优先级

排查 Gemini API 时，第一步看 HTTP status。

状态码	类型	是否重试	常见处理
400	请求错误	否	检查参数、输入格式、请求体
403	权限错误	否	检查 API key、项目权限、账单状态
404	资源错误	否	检查模型名、文件 ID、缓存 ID
429	限流/配额	是	指数退避、排队、降低并发
500	服务端错误	是	有限重试、错误上报
503	服务不可用	是	熔断、降级、备用模型
504	超时	是	拆任务、调超时、异步队列

工程经验：不要把所有错误写进同一个 catch 后统一重试。400、403、404 反复重试没有意义。

2. 429 排查流程

429 通常和 rate limits 有关。Gemini API 的限制可能涉及：

RPM: requests per minute
TPM: tokens per minute
RPD: requests per day

推荐排查顺序：

1. 看一分钟内请求数是否突增。
2. 看输入 token 是否异常变大。
3. 看批处理任务是否和在线任务共用额度。
4. 看多实例是否同时重试。
5. 看当前项目层级和模型限额。

很多 429 不是请求次数太多，而是 TPM 被长上下文打满。

3. 重试策略示例

const RETRYABLE_STATUS = new Set([429, 500, 503, 504]);

function delay(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

function calcBackoff(attempt: number) {
  const base = Math.min(1000 * 2 ** attempt, 8000);
  const jitter = Math.floor(Math.random() * 500);
  return base + jitter;
}

async function callModelWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  let attempt = 0;

  while (true) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.status;

      if (!RETRYABLE_STATUS.has(status) || attempt >= maxRetries) {
        throw error;
      }

      await delay(calcBackoff(attempt));
      attempt += 1;
    }
  }
}

注意：

1. 必须限制最大重试次数。
2. 必须加 jitter，避免所有实例同一时间重试。
3. 业务层要设置最大等待时间。
4. 重试失败后要进入降级逻辑。

4. 超时处理

504 或客户端超时通常和三类因素有关：

输入太大：长文档、代码仓库、图片批量分析会增加响应时间。

网络链路：国内访问官方 API 时，链路波动会直接影响延迟。

模型负载：高峰时段或热门模型可能响应变慢。

建议做法：

1. 长任务拆分为多个小任务。
2. 离线任务进入队列。
3. 面向用户的请求设置短超时。
4. 失败后返回缓存、规则结果或提示进入异步处理。
5. 监控 P50、P95、P99 延迟，而不是只看平均值。

5. 最小模型网关设计

type ModelProvider = "gemini" | "openai" | "anthropic" | "token5u";

type ModelRoute = {
  primary: string;
  fallback?: string[];
  timeoutMs: number;
  maxRetries: number;
};

type ModelCallLog = {
  provider: ModelProvider;
  model: string;
  status: number;
  latencyMs: number;
  inputTokens?: number;
  outputTokens?: number;
  business: string;
};

生产环境中，业务代码不建议直接调用 Gemini API，而是调用模型网关。网关负责：

1. 模型路由。
2. 限流。
3. 重试。
4. 降级。
5. 日志。
6. 成本统计。
7. API key 管理。

这样后续从 Gemini 3.1 Pro Preview 切到 GPT-5.5 或 Claude Opus 4.7，不需要大面积修改业务代码。

6. 国内使用限制

国内团队接 Gemini API，要提前评估这些限制：

网络：官方 API 访问可能出现连接失败、延迟波动或超时。生产环境要做专线、代理链路或聚合接入方案评估。

结算：境外信用卡、美元账单、海外发票和采购流程可能不适合企业内部制度。

数据合规：用户数据、合同、内部文档、图片、音频、代码是否能进入境外模型，需要做分级和脱敏。

运维：官方 API 不会替你做业务侧限流、重试、成本归集和多模型降级。

7. 词元无忧API（token5u API）适用场景

如果项目只做低频 demo，官方 API 足够。以下场景可以评估词元无忧API（token5u API）：

1. 需要同时调用 Gemini、GPT、Claude。
2. 已经有 OpenAI SDK 或 OpenAI 兼容接口。
3. 需要人民币企业结算。
4. 国内访问链路稳定性要求较高。
5. 希望按量计费、无预付、无隐性收费。
6. 希望把多模型调用成本和接入成本降下来。

词元无忧API（token5u API）支持 Gemini、GPT、Claude 等主流模型统一接入，接入方式对标 OpenAI 官方 API，同时支持各家官方格式。建议用同一批真实请求做 POC，对比官方直连和聚合接入的延迟、错误率、429 比例和总成本。

8. 上线检查清单

1. 是否区分 400、403、404、429、500、503、504？
2. 429 是否有指数退避？
3. 重试是否有最大次数？
4. 在线任务和批处理是否隔离？
5. 是否记录 token、状态码、耗时和业务标签？
6. 是否有备用模型？
7. API key 是否进入密钥管理？
8. 国内网络和结算是否验证？
9. 是否有成本告警？
10. 模型名是否集中配置？

跑通 Gemini API 只是第一步。能处理失败，才算具备上线条件。