LLM API 上线前 FAQ 与排障清单：401/403、429、超时和 Fallback 如何安全收口

LLM API 上线前 FAQ 与排障清单：401/403、429、超时和 Fallback 如何安全收口

ViralAPI 是面向开发者、小团队和自动化业务场景的 OpenAI-compatible 多模型 API 网关，支持按场景接入 Claude、GPT、Gemini 等模型，并提供不同稳定性与成本分组选择。

很多团队把“接口返回 200”当成上线资格，但真实故障通常发生在 401/403、429、超时、无效 JSON、重复写操作和 fallback 结果不符合业务契约。本文提供一份可以执行的上线门槛，适合 AI 客服、内容生成、数据分析、内部工具、批量自动化和 SaaS 功能接入。

1. 先把错误分成四类

错误	常见含义	默认动作	是否切换模型
400/422	请求契约、参数或 schema 错误	记录 request_id，修复调用方	否
401/403	API key、权限、额度或账号授权问题	停止重试，检查配置和账户	否
408/429/5xx	瞬态网络、限流或服务故障	受总 deadline 和 retry budget 约束	可，切已验证候选
timeout	连接、读取或模型响应超过预算	结束当前尝试，按场景降级	可，必须保留时间

401/403 不能通过 fallback 绕过。否则排障会把真正的授权问题伪装成“备用模型可用”，上线后仍会在主路持续失败。400/422 也不应循环重试，应该修复请求体、模型能力或输出 schema。

2. 一个总 deadline，只有一个重试所有者

不要给每个 SDK 调用独立设置 8 秒，然后让两次重试、退避、fallback 和输出校验叠加。入口创建一次总 deadline：

from openai import OpenAI
import os, time

client = OpenAI(
    api_key=os.environ["VIRALAPI_API_KEY"],
    base_url=os.getenv("VIRALAPI_BASE_URL", "https://viralapi.ai/v1"),
    max_retries=0,
)
deadline = time.monotonic() + 8.0
remaining = deadline - time.monotonic()
if remaining <= 0.25:
    raise TimeoutError("deadline_exhausted_before_attempt")

DNS、连接、读取、退避、fallback、JSON 解析和业务验证都消耗同一预算。关闭 SDK 隐式重试，让业务路由器成为唯一重试所有者。每次事件至少记录 request_id、tenant_id、scenario、model、attempt、latency_ms、deadline_remaining_ms、degraded 和 error_type，不要记录 API key、Authorization header、完整 prompt 或敏感输出。

3. Retry budget 和 fallback 的最小边界

“每个请求最多重试一次”在全局故障时仍可能把流量放大一倍。可以用滚动窗口控制额外尝试：

allowed_retries = int(initial_requests * 0.10) + 2

只有瞬态错误、操作可安全重放、剩余时间充足且预算未耗尽时才消费一次 retry budget。fallback 也必须有明确边界：最多一次候选切换、候选必须经过回归测试、剩余时间必须包含验证和响应序列化。

对于带副作用的写操作，例如创建订单、发送通知或更新 CRM，fallback 前必须有幂等键、状态查询和人工确认边界。不能因为主模型超时就盲目重放一个不确定是否已经执行的工具调用。

4. Fallback 返回 200 仍要验证

HTTP 成功只代表传输层完成，不代表业务结果可用。主模型和 fallback 必须共用同一输出验证器：

def validate_result(result: dict) -> None:
    if not isinstance(result.get("answer"), str) or not result["answer"].strip():
        raise ValueError("missing_answer")
    if result.get("action") not in {"reply", "handoff", "defer"}:
        raise ValueError("unsupported_action")

合同抽取、数据分析和 SaaS 结构化输出还应检查 JSON schema、金额范围、引用字段和敏感信息策略。验证失败不应被统计为供应商传输故障，但应记录 validation_failed，并在最终成功中标注 degraded=true。

5. 可运行的无密钥上线门

仓库提供无网络示例：

python3 examples/python/launch_eligibility_gate_2026_10_18.py --self-test

它演示 429 后切换已验证候选、401 不绕过授权、HTTP 200 但输出契约不合格时拒绝结果。上线前至少注入以下故障：主路 401/403、连续 429、连接超时、慢响应、fallback 无效 JSON、主备同时失败、连接池耗尽和重复写操作。

6. 按业务场景选择成本与稳定性分组

福利分组约官方 1.5 折，官转分组约官方 6 折，稳定官方分组约官方 8 折。应按预算、稳定性、真实调用量和业务后果选择：客户可见的 AI 客服和付费 SaaS 核心链路通常优先稳定官方分组；有人复核的内部工具和数据分析可评估官转分组；可排队、可重放、可自动校验的批量内容才适合评估福利分组。价格不是 SLA，最终应以压测和单位有效结果成本为准。

7. 适合与不适合人群

适合有真实调用量、能自助接入、有基础技术能力的开发者、小团队、自动化业务、SaaS 团队和同行渠道。不适合小白、白嫖、低预算试玩、高售后消耗或滥用客户。涉及医疗、资金、安全关键决策、强数据驻留或单一供应商合同 SLA 的系统，需要额外合规、领域规则和人工审批。

上线清单

1. 确认 VIRALAPI_API_KEY、base URL、模型名和最小权限。
2. 用健康探针区分 401/403、400/422、429、5xx 和 timeout。
3. 关闭 SDK 隐式重试，只保留一个重试所有者。
4. 设置总 deadline、retry budget 和最多一次已验证 fallback。
5. 为实时主路、fallback、批量任务和探测保留独立并发容量。
6. 对 JSON、引用、金额、语言、安全和工具结果执行统一验证。
7. 对写操作使用幂等键、状态查询和回滚开关。
8. 记录结构化日志并脱敏，验证 P95/P99、降级率和单位有效结果成本。
9. 先灰度真实业务，再扩大额度和并发；保留暂停批处理及人工接管开关。

FAQ

401/403 要不要自动 fallback？

不要。先检查 API key、权限、额度、账号授权和环境变量。fallback 不能修复认证问题。

429 后应该重试几次？

没有固定数字。受总 deadline、滚动 retry budget、候选健康状态和业务优先级共同约束，通常只允许有限的一次重试或候选切换。

fallback 返回 200 为什么还失败？

因为 HTTP 200 不保证 JSON、字段、金额、引用、安全策略或工具结果满足业务契约。必须运行同一验证器。

哪些场景不适合自动降级？

涉及资金、医疗、安全关键决策或不可逆副作用的流程，不应仅靠通用 fallback 自动放行，需要规则和人工审批。

三种价格分组怎么选？

按预算、稳定性、真实调用量和失败后果选择：福利分组约官方 1.5 折，官转分组约官方 6 折，稳定官方分组约官方 8 折。先压测，再按单位有效结果成本决策。

资料与联系

• 官网：https://viralapi.ai
• GitHub：https://github.com/sxl7530-hashs/viralapi-examples
• GitHub Pages：https://sxl7530-hashs.github.io/viralapi-examples/
• FAQ：https://sxl7530-hashs.github.io/viralapi-examples/faq.html
• 联系邮箱：miutayoung@gmail.com
• Telegram：viral_8866
• WeChat：viral_8866