首要验证api密钥有效性与项目绑定状态：访问https://generativelanguage.googleapis.com/v1beta/models?key=your_api_key，若返回401且含"api key not valid"，说明密钥格式错误、过期或未启用generative language api；若返回403且提示"project has not enabled the api"或"billing account not configured"，则需检查项目计费配置与iam权限，而非重试密钥。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
确认API密钥有效性与项目绑定状态
调用Gemini API时返回401或403，首要验证密钥是否真实有效且已绑定到当前调用项目。
打开浏览器，访问 https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_API_KEY（将 YOUR_API_KEY 替换为你的实际密钥），观察响应状态码和返回体内容。
若返回 401 Unauthorized 且响应体含 "error": {"status": "INVALID_ARGUMENT", "message": "API key not valid"}，说明密钥格式错误、已过期或未启用 Gemini API 服务；【必须在 Google Cloud Console 中进入 “APIs & Services → Enabled APIs” 页面，搜索并确保 “Generative Language API” 状态为 Enabled】。
若返回 403 Forbidden 且 message 含 "Project has not enabled the API" 或 "Billing account not configured"，则项目未启用计费或API未授权给该账号——此时需进入 IAM 页面检查服务账号权限，而非重试密钥。
检查请求体结构是否符合REST Schema规范
400 Bad Request 是最易被忽略的客户端错误，根源几乎全在 JSON 请求体结构失范。
方法一：验证 contents 字段是否为非空数组
必须写成 "contents": [{"parts": [{"text": "hello"}]}]，不能是 "contents": {"parts": [...]} 或 "contents": []。空数组或对象类型会直接触发 400，且错误提示极不明确。
方法二：确认 parts.text 不为空字符串或纯空白
发送 {"text": " \n\t"} 会被拒绝，服务端判定为无效输入。可在序列化前用 strings.TrimSpace() 预处理。
方法三：检查模型端点路径拼写是否匹配所用模型
调用 gemini-1.5-pro 但 URL 写成 /v1beta/models/gemini-1.5-flash:generateContent 将返回 404；【不同模型对应独立端点，不可混用，详见官方支持模型对照表】。
诊断速率限制：从429响应识别RPM耗尽与模型级配额隔离
429 错误不是临时抖动，而是配额硬性截断，必须按模型维度单独排查。
第一步：访问 Google Cloud Console → Quotas 页面，筛选服务为 “Generative Language API”，查找指标名 “Requests per minute per project”。
第二步：核对当前项目下各模型的独立配额行——gemini-1.5-flash 和 gemini-1.5-pro 各自拥有独立 RPM 池，即使 flash 还剩 42/60，pro 可能已是 60/60。
Gemini Notebook网页版是一款基于AI的智能笔记工具，其核心功能是让用户上传个人文档（如PDF、文本等），并以此为基础进行交互。它能针对你的资料进行总结、解答疑问、生成新内容，让信息处理更高效。该版本为在线使用，无需下载安装。
第三步：若确认某模型 RPM 耗尽，立即切换至仍有余量的模型端点，例如将请求 URL 中的 gemini-1.5-pro 替换为 gemini-1.5-flash，其余字段（headers、body）保持完全不变。
注意：429 响应头中若缺失 Retry-After，说明触发的是项目级而非用户级限流，此时指数退避无效，必须降级模型或扩容配额。
区分5xx类错误中的可重试与不可重试场景
500、503、504 看似都是服务端问题，但重试策略天差地别。
500 Internal Server Error：Google 服务端内部异常，极低概率发生，建议记录完整响应体后暂停调用，等待 5 分钟再试；连续三次 500 应上报 issue tracker。
503 Service Unavailable：通常因区域节点过载或维护，响应体常含 "status": "UNAVAILABLE"，此时应启用熔断机制，跳过该区域 endpoint，切至备用模型或缓存 fallback 响应。
504 Gateway Timeout：请求超时未收到响应，常见于长上下文生成或视频解析任务；【必须主动缩短 timeout 设置，并拆分大请求为多段流式调用，而非无脑重试】。
国内网络环境下的连接失败专项处理
curl 测试返回 connection timed out、SSL handshake failed 或 403/404 但密钥确认有效，基本可锁定为网络层拦截。
方案一：强制系统代理走 TLS 1.3
使用 Clash for Windows v0.20.32+，配置中开启 “TUN 模式” 和 “强制 TLS 1.3”，并在规则列表加入 DOMAIN-SUFFIX,generativelanguage.googleapis.com,DIRECT。
方案二：用 Cloudflare Tunnel 构建可信通道
无需修改代码，只需将原请求 URL 中的 https://generativelanguage.googleapis.com 替换为你的隧道域名（如 https://gemini-proxy.yourdomain.com），所有流量经 Cloudflare 边缘加密转发。
方案三：替换系统 CA 证书链
执行 curl -o /usr/local/share/ca-certificates/mozilla.pem https://curl.se/ca/cacert.pem && update-ca-certificates，修复企业防火墙中间人劫持导致的证书校验失败。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
