> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 服务端错误通常是临时故障，介绍如何判断根本原因并实现自动重试。

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

## 状态码含义

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

<Accordion title="502 Bad Gateway">
  网关层（如 Nginx）在尝试连接后端服务时失败。这通常意味着后端服务暂时不可用或重启中。
</Accordion>

<Accordion title="503 Service Unavailable">
  服务当前无法处理请求，可能由于系统负载过高、正在部署更新或进行维护。
</Accordion>

## 解决方法

### 使用退避重试

```python theme={null}
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")
```

### 多维度排查

<Steps>
  <Step title="立即重试一次">
    大多数服务端错误是瞬时的，等待几秒后再次请求即可恢复正常。
  </Step>

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

  <Step title="扩大重试间隔">
    如果连续多次失败，建议将等待时间延长至数分钟，并持续观察状态。
  </Step>

  <Step title="判断是否为全局故障">
    如果多个模型的请求均返回 5xx，则可能是 Sub2API 平台级问题。此时可等待平台恢复，或参考 [上游服务不可用](/troubleshooting/upstream-unavailable) 了解详细应对措施。
  </Step>
</Steps>

## 有效预防

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

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

## 状态码含义

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

<Accordion title="502 Bad Gateway">
  网关层（如 Nginx）在尝试连接后端服务时失败。这通常意味着后端服务暂时不可用或重启中。
</Accordion>

<Accordion title="503 Service Unavailable">
  服务当前无法处理请求，可能由于系统负载过高、正在部署更新或进行维护。
</Accordion>

## 解决方法

### 使用退避重试

```python theme={null}
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")
```

### 多维度排查

<Steps>
  <Step title="立即重试一次">
    大多数服务端错误是瞬时的，等待几秒后再次请求即可恢复正常。
  </Step>

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

  <Step title="扩大重试间隔">
    如果连续多次失败，建议将等待时间延长至数分钟，并持续观察状态。
  </Step>

  <Step title="判断是否为全局故障">
    如果多个模型的请求均返回 5xx，则可能是 Sub2API 平台级问题。此时可等待平台恢复，或参考 [上游服务不可用](/troubleshooting/upstream-unavailable) 了解详细应对措施。
  </Step>
</Steps>

## 有效预防

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