错误码说明

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	认证失败（API Key 无效）
403	权限不足（余额不足或 Key 被禁用）
429	请求频率超限
500	服务器内部错误
503	服务不可用（通常是模型 ID 不存在）
524	代理层等待超时（长耗时请求未在窗口内返回完整响应）

常见错误排查

❌ 401 - API Key 无效

可能原因：

• API Key 复制错误（含有多余空格）
• Key 未在控制台创建，或已被删除

解决方案：

1. 去控制台「令牌」页重新复制 Key
2. 确认传递格式：Authorization: Bearer sk-xxx（注意 Bearer 后有空格）

---

❌ 503 - 模型 ID 不存在

可能原因：

• 使用了不支持的模型 ID，如 gpt-4o、claude-3.5-sonnet 等非平台模型

解决方案： 参考支持的模型列表，使用准确的模型 ID，例如：

• ✅ claude-sonnet-4-6
• ✅ gpt-5.1-codex
• ❌ claude-3.5-sonnet（不支持）
• ❌ gpt-4o（不支持）

---

❌ 403 - 余额不足

可能原因：

• 账户余额为 0

解决方案： 登录控制台充值。

---

❌ 429 - 请求过于频繁

解决方案： 添加请求间隔，使用指数退避重试：

import time

for i in range(3):
    try:
        response = client.chat.completions.create(...)
        break
    except Exception as e:
        if "429" in str(e) or "rate limit" in str(e).lower():
            wait = 2 ** i
            print(f"限流，等待 {wait}s...")
            time.sleep(wait)
        else:
            raise

---

❌ Claude Code 连接失败

检查步骤：

# 1. 确认环境变量
echo $ANTHROPIC_BASE_URL   # 应为 https://1xm.ai/
echo $ANTHROPIC_AUTH_TOKEN # 应为 sk-xxx

# 2. 在 Claude Code 内运行诊断
/doctor

注意： 关闭终端代理后重试，代理可能干扰连接。

---

❌ 524 - 长耗时请求代理超时

可能原因：

• 图片生成、4K 输出、多参考图编辑等任务耗时超过代理层等待窗口
• 请求经过 Cloudflare 等代理，源站未在约 120 秒窗口内返回完整响应
• 客户端把同步 HTTP 请求当成长任务队列使用

解决方案：

1. 对短任务可直接重试。
2. 对 4K 生图、图片编辑、多张输出等长任务，使用 1XM 官方异步任务接口：POST /v1/images/tasks。
3. 创建任务后按返回的 poll_url 查询状态，成功后读取 data[].url。
4. 仅调大 SDK 的 timeout 不一定能解决 524，因为 524 通常发生在代理层，而不是客户端本地超时。

参考图片 API 的异步任务说明：GPT-Image-2 图片 API。

---

❌ Connection Timeout

解决方案：

• 关闭终端代理（直连速度更好）
• 设置超时参数：

client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://api.1xm.ai/v1",
    timeout=60.0  # 秒，长任务可适当调大
)

错误响应格式

{
  "error": {
    "message": "The model `gpt-4o` does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

遇到无法解决的问题，请在控制台提交工单。