错误处理与重试 - HiLinkup Docs

应用应根据错误类型决定是否重试。不要对所有失败执行相同策略。

状态码	含义	是否重试
`400`	请求格式或参数错误	否，修正请求
`401`	API Key 无效	否，更换密钥
`403`	权限、策略或上游拒绝	通常否，先排查请求
`404`	端点或模型不存在	否，刷新模型列表
`429`	触发限速或额度限制	是，指数退避
`500`–`504`	服务或上游暂时故障	是，有限次数重试

推荐重试策略

import random
import time

def retry_delay(attempt: int) -> float:
    base = min(2 ** attempt, 8)
    return base + random.uniform(0, 0.5)

最大重试 2–3 次。
使用指数退避和随机抖动。
为整个业务操作设置总超时。
只重试幂等请求，或为非幂等操作设置幂等键。
回退模型前记录原始模型、错误类型和请求 ID。

不要通过删除工具、缩短业务提示词或静默修改用户请求来掩盖兼容性错误。先识别不兼容字段，再进行显式降级。

最后修改于 2026年7月2日