生产环境调用Gemini API异常时，需将技术错误映射为中性业务提示：拦截HTTP状态码与安全关键词、校验响应结构并启用降级文案、按错误码分类提示、分阶段前端提示、严格隔离日志不暴露原始错误。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在生产环境中调用 Gemini API 时遇到模型拒绝回答（如返回空响应、安全拦截、content_filtering 错误或 HTTP 400/429 等状态），系统需避免向用户暴露原始错误信息，而应提供语义清晰、语气中立、符合业务场景的提示。以下是多种可立即落地的异常提示处理方法：
一、HTTP 层级错误拦截与映射
在 API 网关或客户端 SDK 调用层捕获 Gemini 返回的 HTTP 状态码及响应体中的 error 字段，将底层技术错误转换为预定义的业务提示文案，避免泄露模型内部机制。
1、检查响应状态码：若为 400，解析 response.json() 中的 error.status 是否为 "INVALID_ARGUMENT" 或 "FAILED_PRECONDITION"。
2、若 error.message 包含 "blocked", "safety", "content_filter" 等关键词，统一映射为提示语：当前问题涉及敏感内容，我们暂无法提供回答。
3、若状态码为 429，提取 response.headers 中的 "Retry-After" 值，提示：请求过于频繁，请稍后再试。
二、响应结构兜底校验与降级文案
Gemini 可能返回非标准 JSON、空 candidates 数组、或 candidates[0].content.parts 为空列表。需在解析响应前强制校验结构完整性，并启用静态降级文案池，确保前端始终获得可渲染文本。
1、判断 response.candidates 是否存在且长度大于 0；否则返回预设文案：我们正在思考这个问题，请稍等片刻。
2、检查 candidates[0].content.parts 是否为非空数组；若为空，返回：该问题暂时超出当前处理范围。
3、对 parts[0].text 执行 trim() 后判空；若为空字符串，触发二次提示：答案可能需要更多上下文，您可以补充说明吗？。
三、基于错误码的语义化分类提示
Google Cloud 的 Gemini API 在 error.details 中会携带 machine-readable 的错误类型（如 "SAFETY_BLOCKED", "RATE_LIMIT_EXCEEDED", "INVALID_API_KEY"）。应建立错误码到友好提示的映射表，实现精准语义反馈。
1、从 error.details[0].type 提取值，匹配 "type.googleapis.com/google.rpc.ErrorInfo" 结构。
2、若 type 为 "SAFETY_BLOCKED"，返回：为保障交流安全，该内容未被允许生成。
3、若 type 为 "RATE_LIMIT_EXCEEDED"，返回：当前使用量已达上限，请稍后重试。
4、若 type 为 "INVALID_API_KEY" 或 "PERMISSION_DENIED"，返回：服务连接异常，请联系管理员确认配置。
四、前端异步加载态与渐进式提示
当后端尚未返回结果时，前端不应显示空白或闪烁的加载图标，而应分阶段呈现可信度递增的提示，降低用户焦虑感，并隐式管理预期。
1、发起请求后立即显示：正在为您查询相关信息…。
2、等待超时（如 3s）未响应，切换为：处理中，可能需要一点时间。
3、最终失败时，展示带操作引导的终态提示：暂时无法生成回答，点击重试或换种方式提问。
五、日志隔离与用户侧零暴露策略
所有原始错误堆栈、request_id、model_name、raw_response 必须仅写入服务端审计日志，严禁通过 HTTP 响应体、前端 console、或用户可见界面透出任何调试信息。
1、在记录错误日志时，脱敏 request.body 中的 prompt 字段，仅保留前 20 字符 + "…"。
2、响应给前端的 JSON 中，只保留 code（业务错误码）、message（已翻译的提示文案）、retryable（布尔值）三个字段。
3、禁止在 message 字段中出现 "Gemini"、"API"、"500"、"error"、"exception" 等技术词汇，全部替换为中性业务表达：服务暂时不可用。
