401、404、429需快速区分：401是认证失败（如Token过期、签名错误），不可重试；404是资源不存在或路径错误（如Endpoint区域错、v3路径缺失），属配置问题；429是限流触发（如RPM超限），应指数退避重试。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎接口调用失败时，必须快速区分是参数错误导致的永久性失败，还是网络抖动、限流等可恢复的临时性失败，否则盲目重试会加剧限流，硬改参数又可能掩盖真实问题。
看HTTP状态码定大类
拿到响应第一眼先盯住status code，它决定后续所有动作方向。
400、401、403、404 这类 4xx 错误全部归为【参数或配置错误】，不可重试——重试只会重复失败。其中401/403重点查 Authorization 头格式和 Key 权限；404 必须核对 Endpoint 区域标识与 v3 版本路径；400 则要逐项验证 JSON 结构、model 字段完整性、messages 非空等硬性要求。
429 和 503 是唯一允许且应当立即重试的两类：429 表示 RateLimitExceeded，说明当前分钟请求数已超配额；503 表示服务端临时不可用，常见于模型实例冷启动或资源调度延迟。
500、502、504 统一视为服务端异常，需结合 request_id 查日志，不建议无脑重试，尤其 502/504 往往意味着网关层故障，本地重试无效。
细查错误码与 message 字段
仅看 status code 不够，必须读取响应体中的 code 和 message 字段，它们才是精准定位的钥匙。
方法一：匹配标准错误码前缀
RateLimitExceeded.EndpointRPMExceeded → 端点级 RPM 超限，需加退避重试（如指数退避）；
model_not_found → 模型 ID 不存在或未在当前项目开通，不是密钥问题，别去重试；
invalid_request → 请求体语法错或必填字段缺失，比如 messages 传了空数组，必须改参数再发。
方法二：抓 message 中的关键字
出现“cooldown”“all profiles unavailable” → OpenClaw 等工具已触发熔断，此时重试无意义，应切换模型或等待恢复；
出现“signature mismatch”“invalid signature” → 鉴权签名构造错误，检查 Access Key/Secret Key 是否混用、时间戳偏移是否超 300 秒、HMAC-SHA256 签名字符串拼接顺序是否漏字段；
出现“quota exceeded” → 账号级额度用尽，需升配或换 Key，重试无效。
结合 request_id 做交叉验证
第一步：记录完整请求时间、request_id、status code、code 字段、message 字段；
第二步：登录火山引擎控制台 → 方舟平台 → 「可观测性」→ 「请求追踪」，粘贴 request_id 查询全链路日志；
第三步：比对日志中「鉴权阶段」「路由阶段」「模型加载阶段」「推理执行阶段」各环节耗时与状态；
若日志显示「鉴权成功 → 路由失败 → model_not_found」，说明模型 ID 错误，立刻停掉重试，去控制台确认已开通模型列表；
若日志显示「鉴权成功 → 路由成功 → 推理执行超时」，说明是模型侧卡顿，此时可安全重试，但需限制重试次数 ≤ 2 次；
【request_id 在日志中找不到任何记录，只返回 401 或空响应】→ 极大概率是 Authorization 头格式错误，Bearer 后缺空格，或变量未正确注入 curl 命令。
自动化决策树落地建议
① 所有 HTTP 客户端封装层必须内置错误分类逻辑，禁止将 4xx 和 5xx 统一进 retry loop；
② 对 429 响应，强制加入 jittered exponential backoff：首次延迟 100ms，第二次 300ms，第三次 700ms，最多重试 3 次；
③ 对含 “model_not_found” “signature mismatch” 的响应，直接抛出业务异常，写入告警通道，禁止自动重试；
④ 每次调用必须打印 request_id + status code + error code 到业务日志，方便事后回溯；
⑤ 在 CI/CD 流水线中集成 smoke test，每次发布前用最小合法 payload 调用一次 chat/completions，验证 endpoint + key + model 三者连通性。
