API 错误排查

先看 HTTP 状态码，再核对模型支持的端点类型和响应正文。日志可以记录请求 ID 与状态码，但不能记录完整 API Key。

认证与权限

现象	检查与处理
本地提示缺少 RTOC_API_KEY	在当前终端设置环境变量，再重新运行脚本
HTTP 401	检查 Bearer 格式、密钥是否完整；已泄露的密钥应立即撤销并替换
HTTP 403	确认账号、资源组和模型访问权限，不要反复重试相同请求

模型与参数

模型存在但请求失败时，先在 模型广场 检查它支持的端点类型：文本通常调用 /v1/chat/completions，文生图调用 /v1/images/generations，编辑调用 /v1/images/edits，视频从 /v1/videos 创建任务。

HTTP 400 通常需要检查必填字段、JSON 类型、图片 multipart 上传方式、尺寸与模型能力。不要通过猜测连续更换字段；对照 RTOC 生产文档 的当前格式。

限流与服务端错误

HTTP 429 应读取服务端的重试提示，并采用带抖动的指数退避；设置重试次数上限，避免多个客户端同时形成重试风暴。HTTP 5xx 可以有限重试，但非幂等的媒体创建请求应谨慎处理，避免重复计费或创建重复任务。

视频任务超时

轮询 GET /v1/videos/{task_id} 时，应同时设置请求超时、轮询间隔和总等待上限。收到 failed 立即停止；超过上限后保留 task_id，稍后单独查询，而不是无限阻塞进程。任务完成后再调用 GET /v1/videos/{task_id}/content。