Qwen3.7-Max 的 API 调用错误该如何重试并理解错误码？

Qwen3.7-Max API 调用失败时，不能看到错误就统一重试。正确做法是同时读取 HTTP 状态码、响应体中的 code 与 message，再把错误分为可重试的临时故障、需要降速的限流，以及必须修改请求或账号状态的永久故障；只有网络超时、部分 429 和部分 5xx 适合有限次数的指数退避重试。

先保存完整错误上下文

一次百炼 API 错误通常包含两层信息。HTTP 状态码说明认证、请求、限流或服务端处理的大类，响应体中的业务错误码则说明更具体的原因。生产代码至少要记录状态码、业务 code、脱敏后的 message、请求标识、模型名、尝试次数和耗时。

不要记录 API Key、完整提示词或未经脱敏的工具参数。请求标识尤其重要：当持续出现 5xx 或超时时，它能帮助平台支持人员定位服务端调用，而单独一张“请求失败”截图通常无法追踪。

哪些错误应该重试

错误类型	常见含义	处理方式
网络连接中断、读取超时	客户端未取得完整响应	有限重试，并确认原请求是否可能已被服务端接收
429 限流	RPS、RPM、TPS、TPM 或突发速率超过限制	降低并发，按指数退避加随机抖动；额度耗尽则不能靠短时重试解决
500、502、503、504	临时服务异常、网关故障或超时	有限重试，持续失败时停止并保留请求标识
400	JSON、参数、消息序列或模型能力不匹配	修改请求，不原样重试
401、403	密钥无效、权限不足、服务未开通或账号状态异常	修复认证、权限或账号，不自动重试
404	接口地址、模型名或资源不存在	核对 endpoint 与模型标识，不原样重试

HTTP 状态码只是第一层判断。比如 429 既可能是短时速率限制，也可能是分配额度已经耗尽。前者等待并降速后可能恢复，后者需要调整配额、套餐或模型，连续睡眠重试只会延迟失败。

指数退避为什么还要加入随机抖动

固定每秒重试一次会让同时失败的客户端在同一时刻再次请求，形成新的流量尖峰。指数退避让等待时间逐步增长，随机抖动则把不同客户端的重试时间打散。百炼官方限流最佳实践建议对 429 与 5xx 使用这一组合，而不是无限或固定间隔重试。

import random
import time

RETRYABLE_STATUS = {429, 500, 502, 503, 504}

def call_with_retry(send_request, max_attempts=5,
                    base_delay=1.0, max_delay=30.0):
    last_error = None

    for attempt in range(max_attempts):
        try:
            response = send_request()
        except (TimeoutError, ConnectionError) as exc:
            last_error = exc
        else:
            if response.status_code < 400:
                return response

            error = response.json()
            code = error.get("code", "")

            if response.status_code not in RETRYABLE_STATUS:
                raise RuntimeError(
                    f"non-retryable: status={response.status_code}, code={code}"
                )

            last_error = RuntimeError(
                f"retryable: status={response.status_code}, code={code}"
            )

        if attempt == max_attempts - 1:
            break

        ceiling = min(max_delay, base_delay * (2 ** attempt))
        time.sleep(random.uniform(0, ceiling))

    raise RuntimeError("retry budget exhausted") from last_error

示例采用全抖动：每次在零到当前退避上限之间随机等待。实际项目还应识别 SDK 抛出的超时、连接和限流异常，而不是假设所有失败都有 HTTP 响应。若服务返回 Retry-After，应优先遵循该等待提示，并设置总耗时上限。

理解常见错误码

400：请求本身需要修改

400 通常表示 JSON 格式、必填字段、参数范围、模型名称或消息序列不符合接口要求。工具调用场景还要检查消息顺序：带有工具调用的 assistant 消息后，需要按协议补充对应的工具结果，不能直接接一条无关用户消息。原样重试不会改变请求，因此应先打印脱敏后的请求结构并与当前接口文档对照。

401 与 403：认证和访问条件不成立

401 优先检查 Authorization 请求头、API Key 是否有效，以及环境变量是否加载。403 可能涉及服务未开通、模型权限、地域、内容策略或账号状态。此类错误在配置改变前通常是确定性的，自动重试既浪费配额，也会掩盖真正的部署问题。

429：限流不等于所有额度都能自动恢复

百炼可能按请求数和 Token 用量限流，也可能限制突发增长速度。记录业务错误码后再决定动作：速率类限制应降低并发、平滑发送并退避；分配配额不足应检查控制台限额和用量；免费额度到期则需要切换可用模型或计费方式。若单次低频请求也立即返回 429，还应检查是否误用了模型不支持的异步请求头。

5xx 与请求超时：重试但要有预算

500、502、503 和 504 多数属于服务或网关临时故障，可以重试，但最多尝试几次并限制总等待时间。长文本或长时间无数据的流式连接也可能超时；这时除重试外，还要缩短输入、限制输出长度，并确认客户端读取超时大于业务允许的首 Token 等待时间。

流式调用如何判断能否重试

请求在收到任何输出前失败，通常可以作为完整请求重试。已经收到部分流式内容后再断开，则不能简单把第二次结果拼到第一次结果后面，因为模型可能重新生成不同内容。客户端应丢弃不完整结果并重新发起一次独立请求，或者把部分结果标记为失败，交由上层业务决定是否继续。

如果调用会触发外部工具、写数据库、发送消息或创建订单，重试前必须加入幂等键或业务去重。API 超时只说明客户端没有按时取得结果，不证明服务端没有处理；无保护地重试可能造成重复副作用。

生产环境需要三道保护

1. 重试预算：同时限制最大次数、单次超时和总耗时，预算耗尽后明确失败。
2. 并发控制：使用队列、信号量或令牌桶平滑请求，避免每个工作进程独立重试形成洪峰。
3. 熔断与降级：5xx 持续升高时暂停向故障端点施压，必要时切换经过验证的备用模型，并保留告警。

验证策略时，可以在测试环境模拟 400、429、500 和网络超时。预期结果应分别是：400 立即失败；429 和 5xx 按抖动退避；网络超时消耗有限重试预算；超过预算后向上层返回包含状态码、业务码和请求标识的错误。这样才能证明代码不是“遇错循环”，而是按错误语义恢复。

最终判断顺序

先解析 HTTP 状态码和业务错误码，再判断请求是否改变后才可能成功。参数、认证、权限、余额和模型名问题先修复；短期限流通过降并发和抖动退避恢复；临时 5xx 与网络超时使用有限预算重试。任何涉及副作用的调用都先保证幂等，持续失败则停止重试并用请求标识排查，而不是把一次故障放大成重试风暴。