AI API 返回 503 Service Unavailable 怎么处理

用户可见现象与最小日志

503可能伴随Retry-After、厂商错误类型、容量提示或维护信息，也可能只返回空错误页。日志应记录状态、Retry-After、request ID、路由节点、并发、排队时间和总耗时，避免保存敏感输入。

2026-08-23T14:05:00Z status=503 retry_after=30 queue=2.4s total=2.5s request_id=req_yyy

故障位置判断

客户端大量并发可触发服务保护；企业出口或自有代理可能没有健康后端；网关可能因服务发现为空而返回503；上游模型服务可能维护、过载或依赖不可用。先看响应头和服务状态页，再用最小请求判断是否与输入、模型或区域相关。

十分钟快速排查

保存Retry-After与request ID；检查官方状态页；暂停自动重试风暴；将并发降到安全水平；用短输入和非流式请求复现；检查自有负载均衡健康节点；比较其他已授权模型；设置临时队列上限；决定快速失败或降级；持续失败则联系服务方。

curl -i --max-time 30 https://api.example.com/v1/test
# 若响应含 Retry-After: 30，至少等待建议时间再进行有限重试

Retry-After 与退避

RFC 9110允许503携带Retry-After，值可以是HTTP日期或秒数。客户端应优先遵循；缺失时才使用有上限的指数退避与抖动。设置最大尝试次数和整体截止时间，排队超过业务时限时应快速失败。

幂等性和重试放大

503不证明上游完全没有执行请求。若请求在业务处理后、响应返回前失败，重复提交可能造成双写或重复工具调用。写操作需要幂等键和结果查询；多层SDK、网关和业务代码不能各自独立重试，否则尝试次数会相乘。

临时恢复与长期预防

临时措施包括降低并发、暂停批处理、启用只读缓存、缩短非必要输入或切换经过验证的容量池。长期应做容量测试、并发隔离、队列上限、负载保护、降级和状态页订阅，并监控503率、排队时间、健康实例数和恢复耗时。

何时联系服务提供方

在遵循Retry-After后仍持续失败、状态页未披露、多个最小请求和不同时间窗口均复现，或错误集中于特定账户/模型时，提交request ID、UTC时间、区域、模型、SDK版本和脱敏响应。不要发送密钥或用户原文。

过载、维护与健康检查的区分

503的处置取决于来源。响应带明确维护窗口和Retry-After时，客户端应停止高频探测；自有负载均衡显示零健康实例时，要核对健康检查路径、端口、证书和启动时间；仅高并发触发时，检查服务队列、并发配额和保护策略。对比低并发最小请求、原业务请求和另一已授权区域，能区分输入相关、容量相关与区域相关问题。所有对照使用同一模型版本和配置，并记录时间，避免变量同时变化。

设计不会形成重试风暴的客户端

客户端首先读取Retry-After；没有该字段时采用指数退避加随机抖动，并设置最大尝试次数、总截止时间和并发上限。重试预算应由调用链统一持有，例如入口最多允许两次总尝试，下游SDK关闭隐式重试。进入排队前检查剩余预算，预算不足直接返回可解释错误。批处理任务可延迟重排，交互请求应快速失败或使用经过验证的降级结果。不要在503时无条件切换模型，因为参数、语义、成本和数据权限可能不同。

容量恢复后的验证清单

服务恢复后先以少量探测确认成功率和延迟，再阶梯式恢复流量，每一阶观察队列长度、健康实例数、503率、P95/P99和依赖错误。若指标恶化立即停止升流，而不是等待完全过载。验证应覆盖读请求、受幂等保护的写请求、流式连接、长输入和常见模型；不得用真实敏感数据做故障演练。只有在预先定义的观察期内持续满足SLO，才解除临时限流和降级。实际阈值属于站点运行数据，未测量时标为待验证。

运营记录与供应商工单

事故记录应保留UTC起止时间、受影响接口和区域、请求量、503比例、Retry-After分布、用户影响以及采取的限流动作。提交供应商工单时提供若干脱敏request ID、响应头、SDK版本、模型标识和最小复现步骤，不上传密钥、完整提示词或个人数据。若供应商解释与本地证据冲突，继续通过时间线和追踪字段核对。长期容量计划使用峰值并发、输入输出token分布和恢复耗时，而不是只看日均请求。

面向用户的错误呈现

交互请求可显示服务暂时不可用、建议等待时间和追踪ID；Retry-After缺失时不要编造恢复时刻。批处理任务进入有容量上限的延迟队列，并向用户显示真实状态。若采用缓存或替代结果，要明确数据时间和功能限制。所有公开状态必须来自实际监控或供应商公告，未知恢复时间标为UNKNOWN。

工单关闭标准

客服回复不得把暂时缓解等同永久修复。关闭工单前核对用户侧最后一次失败时间、服务端指标与实际恢复窗口，确认限流或降级是否仍启用，并保留复发时的升级路径。证据不足时保持观察状态。

503 和 429 有什么区别？

429 通常表示请求方触发速率或配额限制；503 表示服务当前不可用，但应以具体服务商错误说明为准。