错误码与重试

HyperAI Relay 是透明代理,大多数错误码直接来自 Anthropic 上游,但也有几个是我们自己定义的(余额不足、配额超限、老路径废弃)。这篇文档把所有你可能碰到的错误码列齐,并给出推荐的重试策略。

错误码速查表

HTTP 来源 含义 建议动作
200 — 成功 —
400 客户端 / 上游 请求格式错误(缺字段、模型名错、JSON schema 不符) 不要重试,检查 payload
401 relay API Key 无效或已吊销 去 /app/keys 重新生成
402 relay 账户余额不足 去 /app/topup 兑换
403 relay 配额超限(Memory quota / Files quota) 清理 /app/memories 或升级 Pro Plan
410 relay 老路径已废弃(例如某些 legacy endpoint) 迁移到新 endpoint
429 上游 / relay 速率限制 / 并发限制 指数退避后重试(见下)
500 上游 Anthropic 内部错误,或我们的 gateway bug 重试最多 3 次,仍失败请发邮件
502 / 503 / 504 上游 / 网络 上游暂时不可用 / 我们到 Anthropic 的链路超时 指数退避后重试

重试哪些,不重试哪些

应该重试:429 / 500 / 502 / 503 / 504 —— 这些都是暂时性错误,重试能救。

不应该重试:400 / 401 / 402 / 403 / 410 —— 这些都是"你做错了什么",重试也不会变对。

推荐的重试策略

最多 3 次,指数退避,第一次 2 秒,第二次 4 秒,第三次 8 秒(共 14 秒内完成)。

Python 示例(用官方 SDK 的内置重试)

Anthropic 官方 SDK 自带重试,你只需要配一下:

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.hyper-ailab.com",
    api_key="sk-relay-xxx",
    max_retries=3,     # 默认 2,建议 3
    timeout=60.0,      # 秒,默认 10 分钟,按需调短
)

msg = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hi"}],
)

SDK 默认对 APIConnectionError / APITimeoutError / 408 / 409 / 429 / >=500 重试,完全符合我们的建议。不用自己写重试循环。

手写重试(不用 SDK 时)

import time
import httpx

def call_with_retry(payload, max_retries=3):
    backoff = 2
    for attempt in range(max_retries):
        resp = httpx.post(
            "https://api.hyper-ailab.com/v1/messages",
            headers={
                "x-api-key": "sk-relay-xxx",
                "anthropic-version": "2023-06-01",
            },
            json=payload,
            timeout=60.0,
        )
        if resp.status_code < 400:
            return resp.json()
        if resp.status_code in (429, 500, 502, 503, 504):
            if attempt < max_retries - 1:
                time.sleep(backoff)
                backoff *= 2
                continue
        # 不可重试或重试用尽
        resp.raise_for_status()

具体错误消息的处理

401 — API Key 无效

返回 body 典型格式:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

可能的原因:

  • Key 写错了 / 复制时漏了字符
  • Key 已经在 /app/keys 里被你自己 revoke
  • Key 格式不对(必须是 sk-relay- 开头)

解决:去 /app/keys 重新生成一个。

402 — 余额不足

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Account balance is insufficient for this request"
  }
}

解决:去 /app/topup 兑换一张兑换码。详见 账户与兑换码。

403 — 配额超限

通常是 Memory quota 或 Files quota 满了:

{
  "type": "error",
  "error": {
    "type": "quota_exceeded",
    "message": "Memory quota exceeded: 52428800/52428800 bytes"
  }
}

解决方案三选一:

  1. 去 /app/memories 删一些旧的、用不上的条目
  2. 升级 Pro Plan(Memory quota 从 50MB 涨到 500MB)
  3. 把 Memory 一键导出成 JSON,本地归档后清空

429 — 速率限制

来自上游 Anthropic 的并发限制。原样透传:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

我们没改这个错误,因为我们不知道你的"合理速率"是多少 —— 按 SDK 的退避重试就行。如果长期卡 429,考虑分散调用时间、或者订阅 Pro Plan 获得独立 workspace(独立 workspace 的并发额度是硬隔离的)。

500 / 502 / 503 / 504 — 上游异常

可能的原因:

  • Anthropic 官方出故障(每个月会有一两次小抖动)
  • 我们的 gateway 发布时短暂抖动(我一般在低峰期发,但不保证 0 downtime)
  • 日本节点到 Anthropic 的国际链路波动

按重试策略重试;如果 5 分钟内都不恢复,先看 hyper-ailab.com 有没有状态公告,再发邮件:admin@hyper-ailab.com,带上时间戳。

错误日志在哪里

每次请求(包括失败)都会在 /app/usage 里留下一条记录,含:

  • 时间戳
  • 模型
  • 状态码
  • 错误类型(如果失败)
  • token 用量(成功才有)

如果你要报 bug,先去这里找那条记录,附上 request_id(页面可以复制),我这边能秒级定位到归档日志。

联系支持

  • 邮件:admin@hyper-ailab.com
  • 响应时间:普通问题 24 小时,Pro 订阅用户 12 小时优先
  • 详见 联系我们

下一步