500 / 502 / 503 服务端错误排查

当你收到 500、502 或 503 响应时，通常表示 Sub2API 服务端或其上游组件出现了临时性故障。这类错误往往不是你的请求本身有问题，而是通过合理的重试和等待，大多数情况下可以自动恢复。

状态码含义

500 Internal Server Error

Sub2API 服务端内部发生未预期的错误。可能是系统组件异常、数据格式兼容性问题，或上游返回了不可解析的内容。

502 Bad Gateway

网关层（如 Nginx）在尝试连接后端服务时失败。这通常意味着后端服务暂时不可用或重启中。

503 Service Unavailable

服务当前无法处理请求，可能由于系统负载过高、正在部署更新或进行维护。

解决方法

使用退避重试

import time
import random


def safe_request(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if any(code in str(e) for code in ["500", "502", "503"]):
                wait = (2 ** attempt) + random.uniform(0, 2)
                time.sleep(wait)
            else:
                raise
    raise Exception("Service temporarily unavailable")

多维度排查

立即重试一次

大多数服务端错误是瞬时的，等待几秒后再次请求即可恢复正常。

尝试切换模型

如果失败仅发生在某个特定模型上，说明问题出在该模型的上游供应商。切换到其他模型可快速恢复服务。

扩大重试间隔

如果连续多次失败，建议将等待时间延长至数分钟，并持续观察状态。

判断是否为全局故障

如果多个模型的请求均返回 5xx，则可能是 Sub2API 平台级问题。此时可等待平台恢复，或参考上游服务不可用了解详细应对措施。

有效预防

对所有 API 调用实现带退避的自动重试机制
在关键业务场景中准备模型降级方案（当首选模型不可用时自动切换备选模型）
监控 5xx 错误率，持续失败时及时告警

状态码含义

500 Internal Server Error

Sub2API 服务端内部发生未预期的错误。可能是系统组件异常、数据格式兼容性问题，或上游返回了不可解析的内容。

502 Bad Gateway

网关层（如 Nginx）在尝试连接后端服务时失败。这通常意味着后端服务暂时不可用或重启中。

503 Service Unavailable

服务当前无法处理请求，可能由于系统负载过高、正在部署更新或进行维护。

解决方法

使用退避重试

import time
import random


def safe_request(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if any(code in str(e) for code in ["500", "502", "503"]):
                wait = (2 ** attempt) + random.uniform(0, 2)
                time.sleep(wait)
            else:
                raise
    raise Exception("Service temporarily unavailable")

多维度排查

立即重试一次

大多数服务端错误是瞬时的，等待几秒后再次请求即可恢复正常。

尝试切换模型

如果失败仅发生在某个特定模型上，说明问题出在该模型的上游供应商。切换到其他模型可快速恢复服务。

扩大重试间隔

如果连续多次失败，建议将等待时间延长至数分钟，并持续观察状态。

判断是否为全局故障

如果多个模型的请求均返回 5xx，则可能是 Sub2API 平台级问题。此时可等待平台恢复，或参考上游服务不可用了解详细应对措施。

有效预防

对所有 API 调用实现带退避的自动重试机制
在关键业务场景中准备模型降级方案（当首选模型不可用时自动切换备选模型）
监控 5xx 错误率，持续失败时及时告警

​状态码含义

​解决方法

​使用退避重试

​多维度排查

​有效预防

​状态码含义

​解决方法

​使用退避重试

​多维度排查

​有效预防

状态码含义

解决方法

使用退避重试

多维度排查

有效预防

状态码含义

解决方法

使用退避重试

多维度排查

有效预防