这篇按生产排查手册写适合已经把 Gemini API 接进后端服务的开发者。目标不是介绍模型能力而是把错误码、限流、重试、超时、国内访问和多模型降级讲清楚。1. 错误码优先级排查 Gemini API 时第一步看 HTTP status。状态码类型是否重试常见处理400请求错误否检查参数、输入格式、请求体403权限错误否检查 API key、项目权限、账单状态404资源错误否检查模型名、文件 ID、缓存 ID429限流/配额是指数退避、排队、降低并发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推荐排查顺序看一分钟内请求数是否突增。看输入 token 是否异常变大。看批处理任务是否和在线任务共用额度。看多实例是否同时重试。看当前项目层级和模型限额。很多 429 不是请求次数太多而是 TPM 被长上下文打满。3. 重试策略示例constRETRYABLE_STATUSnewSet([429,500,503,504]);functiondelay(ms:number){returnnewPromise(resolvesetTimeout(resolve,ms));}functioncalcBackoff(attempt:number){constbaseMath.min(1000*2**attempt,8000);constjitterMath.floor(Math.random()*500);returnbasejitter;}asyncfunctioncallModelWithRetryT(fn:()PromiseT,maxRetries3):PromiseT{letattempt0;while(true){try{returnawaitfn();}catch(error:any){conststatuserror?.status;if(!RETRYABLE_STATUS.has(status)||attemptmaxRetries){throwerror;}awaitdelay(calcBackoff(attempt));attempt1;}}}注意必须限制最大重试次数。必须加 jitter避免所有实例同一时间重试。业务层要设置最大等待时间。重试失败后要进入降级逻辑。4. 超时处理504 或客户端超时通常和三类因素有关输入太大长文档、代码仓库、图片批量分析会增加响应时间。网络链路国内访问官方 API 时链路波动会直接影响延迟。模型负载高峰时段或热门模型可能响应变慢。建议做法长任务拆分为多个小任务。离线任务进入队列。面向用户的请求设置短超时。失败后返回缓存、规则结果或提示进入异步处理。监控 P50、P95、P99 延迟而不是只看平均值。5. 最小模型网关设计typeModelProvidergemini|openai|anthropic|token5u;typeModelRoute{primary:string;fallback?:string[];timeoutMs:number;maxRetries:number;};typeModelCallLog{provider:ModelProvider;model:string;status:number;latencyMs:number;inputTokens?:number;outputTokens?:number;business:string;};生产环境中业务代码不建议直接调用 Gemini API而是调用模型网关。网关负责模型路由。限流。重试。降级。日志。成本统计。API key 管理。这样后续从 Gemini 3.1 Pro Preview 切到 GPT-5.5 或 Claude Opus 4.7不需要大面积修改业务代码。6. 国内使用限制国内团队接 Gemini API要提前评估这些限制网络官方 API 访问可能出现连接失败、延迟波动或超时。生产环境要做专线、代理链路或聚合接入方案评估。结算境外信用卡、美元账单、海外发票和采购流程可能不适合企业内部制度。数据合规用户数据、合同、内部文档、图片、音频、代码是否能进入境外模型需要做分级和脱敏。运维官方 API 不会替你做业务侧限流、重试、成本归集和多模型降级。7. 词元无忧APItoken5u API适用场景如果项目只做低频 demo官方 API 足够。以下场景可以评估词元无忧APItoken5u API需要同时调用 Gemini、GPT、Claude。已经有 OpenAI SDK 或 OpenAI 兼容接口。需要人民币企业结算。国内访问链路稳定性要求较高。希望按量计费、无预付、无隐性收费。希望把多模型调用成本和接入成本降下来。词元无忧APItoken5u API支持 Gemini、GPT、Claude 等主流模型统一接入接入方式对标 OpenAI 官方 API同时支持各家官方格式。建议用同一批真实请求做 POC对比官方直连和聚合接入的延迟、错误率、429 比例和总成本。8. 上线检查清单是否区分 400、403、404、429、500、503、504429 是否有指数退避重试是否有最大次数在线任务和批处理是否隔离是否记录 token、状态码、耗时和业务标签是否有备用模型API key 是否进入密钥管理国内网络和结算是否验证是否有成本告警模型名是否集中配置跑通 Gemini API 只是第一步。能处理失败才算具备上线条件。
Gemini API 报错、限流、超时：生产排查手册
发布时间：2026/5/19 19:07:55
这篇按生产排查手册写适合已经把 Gemini API 接进后端服务的开发者。目标不是介绍模型能力而是把错误码、限流、重试、超时、国内访问和多模型降级讲清楚。1. 错误码优先级排查 Gemini API 时第一步看 HTTP status。状态码类型是否重试常见处理400请求错误否检查参数、输入格式、请求体403权限错误否检查 API key、项目权限、账单状态404资源错误否检查模型名、文件 ID、缓存 ID429限流/配额是指数退避、排队、降低并发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推荐排查顺序看一分钟内请求数是否突增。看输入 token 是否异常变大。看批处理任务是否和在线任务共用额度。看多实例是否同时重试。看当前项目层级和模型限额。很多 429 不是请求次数太多而是 TPM 被长上下文打满。3. 重试策略示例constRETRYABLE_STATUSnewSet([429,500,503,504]);functiondelay(ms:number){returnnewPromise(resolvesetTimeout(resolve,ms));}functioncalcBackoff(attempt:number){constbaseMath.min(1000*2**attempt,8000);constjitterMath.floor(Math.random()*500);returnbasejitter;}asyncfunctioncallModelWithRetryT(fn:()PromiseT,maxRetries3):PromiseT{letattempt0;while(true){try{returnawaitfn();}catch(error:any){conststatuserror?.status;if(!RETRYABLE_STATUS.has(status)||attemptmaxRetries){throwerror;}awaitdelay(calcBackoff(attempt));attempt1;}}}注意必须限制最大重试次数。必须加 jitter避免所有实例同一时间重试。业务层要设置最大等待时间。重试失败后要进入降级逻辑。4. 超时处理504 或客户端超时通常和三类因素有关输入太大长文档、代码仓库、图片批量分析会增加响应时间。网络链路国内访问官方 API 时链路波动会直接影响延迟。模型负载高峰时段或热门模型可能响应变慢。建议做法长任务拆分为多个小任务。离线任务进入队列。面向用户的请求设置短超时。失败后返回缓存、规则结果或提示进入异步处理。监控 P50、P95、P99 延迟而不是只看平均值。5. 最小模型网关设计typeModelProvidergemini|openai|anthropic|token5u;typeModelRoute{primary:string;fallback?:string[];timeoutMs:number;maxRetries:number;};typeModelCallLog{provider:ModelProvider;model:string;status:number;latencyMs:number;inputTokens?:number;outputTokens?:number;business:string;};生产环境中业务代码不建议直接调用 Gemini API而是调用模型网关。网关负责模型路由。限流。重试。降级。日志。成本统计。API key 管理。这样后续从 Gemini 3.1 Pro Preview 切到 GPT-5.5 或 Claude Opus 4.7不需要大面积修改业务代码。6. 国内使用限制国内团队接 Gemini API要提前评估这些限制网络官方 API 访问可能出现连接失败、延迟波动或超时。生产环境要做专线、代理链路或聚合接入方案评估。结算境外信用卡、美元账单、海外发票和采购流程可能不适合企业内部制度。数据合规用户数据、合同、内部文档、图片、音频、代码是否能进入境外模型需要做分级和脱敏。运维官方 API 不会替你做业务侧限流、重试、成本归集和多模型降级。7. 词元无忧APItoken5u API适用场景如果项目只做低频 demo官方 API 足够。以下场景可以评估词元无忧APItoken5u API需要同时调用 Gemini、GPT、Claude。已经有 OpenAI SDK 或 OpenAI 兼容接口。需要人民币企业结算。国内访问链路稳定性要求较高。希望按量计费、无预付、无隐性收费。希望把多模型调用成本和接入成本降下来。词元无忧APItoken5u API支持 Gemini、GPT、Claude 等主流模型统一接入接入方式对标 OpenAI 官方 API同时支持各家官方格式。建议用同一批真实请求做 POC对比官方直连和聚合接入的延迟、错误率、429 比例和总成本。8. 上线检查清单是否区分 400、403、404、429、500、503、504429 是否有指数退避重试是否有最大次数在线任务和批处理是否隔离是否记录 token、状态码、耗时和业务标签是否有备用模型API key 是否进入密钥管理国内网络和结算是否验证是否有成本告警模型名是否集中配置跑通 Gemini API 只是第一步。能处理失败才算具备上线条件。
