错误码

Sakrylle API 在两层之间传递错误：网关层（鉴权、计费、路由）和 上游层（OpenAI / Anthropic 实际服务）。两层都遵循 HTTP 状态码语义，但响应体格式略有差异——本页帮你区分并定位问题。

HTTP 状态码

状态码	含义	来源	处理建议
400 Bad Request	请求体格式错误、字段缺失、模型名拼写错	网关 / 上游	检查 JSON 是否合法，参照 API 参考 校对必填字段
401 Unauthorized	缺少 Authorization 头，或 Key 已被撤销	网关	见 鉴权
402 / 余额不足	账户余额或套餐额度耗尽	网关	在 控制台 充值或升级套餐
403 Forbidden	Key 有效但分组未开放该模型	网关	检查 模型与计费 中该模型所属分组
404 Not Found	模型名不存在 / 路由不存在	网关 / 上游	参照 模型与计费 中"不存在的模型"列表
429 Too Many Requests	短时间内超出网关或上游限流	网关 / 上游	指数退避重试，见下方重试策略
500 Internal Server Error	网关或上游内部错误	网关 / 上游	短暂重试；持续出现请联系 support
502 Bad Gateway	上游连接失败或返回非法响应	网关	通常上游波动，重试
503 Service Unavailable	上游主动拒绝（过载 / 维护）	上游	重试，关注 status.sakrylle.com
504 Gateway Timeout	上游响应超时	网关	检查 prompt 是否过大，必要时减少 max_tokens 或拆分请求

网关业务错误码

除标准 HTTP 状态码外，网关在响应体中返回细分的业务错误码，帮助精确定位问题：

错误码	HTTP 状态码	含义	处理建议
GROUP_DELETED	403	API Key 绑定的分组已被删除	在 控制台 重新创建 Key 并绑定有效分组
GROUP_DISABLED	403	API Key 绑定的分组已被禁用	联系管理员启用分组，或切换到其他分组的 Key
GROUP_NOT_ALLOWED	403	当前请求的分组不允许该操作	检查 OAuth token 的授权分组是否正确
GROUP_OVERRIDE_UNSUPPORTED	409	当前分组不支持通过模型名前缀覆盖分组	确认 OAuth token 与目标分组的兼容性
GROUP_UNAVAILABLE	400	指定的分组不可用	检查分组 ID 是否正确，或联系管理员确认分组状态
SUBSCRIPTION_NOT_FOUND	403	订阅不存在或已过期	在 控制台 续订或切换到钱包余额模式
SUBSCRIPTION_INVALID	403	订阅无效（套餐类型与请求不匹配）	检查当前套餐是否支持该模型或接口
USAGE_LIMIT_EXCEEDED	429	用量超过限额（日/周/月限额或总额度）	等待限额重置，或升级套餐 / 充值
INSUFFICIENT_BALANCE	403/402	账户余额不足	在 控制台 充值
api_key_in_query_deprecated	400	通过查询参数传入 API Key（已弃用）	改用 Authorization: Bearer <key> 请求头

平台特定错误格式

Sakrylle 网关透传上游原生错误格式。不同平台的错误响应结构不同：

Anthropic 原生格式

/v1/messages、/v1/messages/count_tokens 返回的错误：

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Request not allowed"
  }
}

顶层 type: "error" 是 Anthropic 风格的标识。error.type 可能的值包括 invalid_request_error、authentication_error、permission_error、rate_limit_error、api_error 等。

Google 原生格式

部分 Google 平台模型返回的错误：

{
  "error": {
    "code": 403,
    "message": "Permission denied",
    "status": "permission_denied"
  }
}

error.status 使用 Google API Design Guide 的标准状态枚举，如 permission_denied、resource_exhausted、invalid_argument 等。

响应体结构

OpenAI 兼容格式

/v1/chat/completions、/v1/responses、/v1/images/* 走这一格式。

{
  "error": {
    "message": "Invalid model: gpt-foo",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

字段含义：

• message — 人类可读描述
• type — 错误大类：invalid_request_error、authentication_error、rate_limit_error、api_error 等
• code — 细分编码（不同上游字段名不完全一致，建议优先按 HTTP 状态码分支）

Anthropic 原生格式

/v1/messages、/v1/messages/count_tokens 走这一格式。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Field required"
  }
}

顶层 type: "error" 是 Anthropic 风格的标识，可用来快速识别这是错误而非正常响应。

网关错误 vs 上游错误

类别	谁产生	典型 message	重试是否有效
网关错误	Sakrylle 网关	unauthorized、insufficient quota、model not configured	否——必须先解决账号/配置问题
上游错误（透传）	OpenAI / Anthropic	rate_limit_exceeded、overloaded_error、internal_server_error	是——指数退避重试

判断小窍门：

• 状态码 4xx + message 涉及 "key"、"quota"、"plan"、"group" → 网关错误
• 状态码 5xx 或 429 + message 涉及 "overloaded"、"upstream"、"timeout" → 上游错误

常见排查清单

• Authorization: Bearer <key> 头是否完整（前缀 Bearer 不能漏）
• 模型名是否在 GET /v1/models 返回的列表里
• 账号是否有该模型所属分组的访问权限
• 控制台余额是否大于本次请求的预估成本
• 请求体是否合法 JSON（可用 jq . 本地验证）
• max_tokens 是否合理；是否被上游 context 限制截断
• 高并发场景是否触发限流（看 429 是否成簇出现）
• status.sakrylle.com 是否报告上游异常

重试策略

对 429、500、502、503、504 应当重试；对 400、401、403、404 不应重试，先修请求或账号配置。

推荐参数：

• 指数退避：delay = base * 2^attempt，base 取 1 秒
• 抖动：在 delay 上叠加 ±20% 随机抖动，避免雪崩
• 上限：最多 5 次重试，单次最长等待 30 秒
• 总预算：单次业务调用总耗时不超过 60 秒

伪代码：

import random, time

def retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RetryableError as e:
            if attempt == max_attempts - 1:
                raise
            delay = min(30, (2 ** attempt)) * (1 + random.uniform(-0.2, 0.2))
            time.sleep(delay)

如果你使用官方 SDK，openai 与 anthropic 的 Python / Node 客户端都自带重试逻辑，默认对 429 与 5xx 退避；通常只需设置 max_retries 即可。

联系支持

把以下信息发到 support@sakrylle.com：

• 账号邮箱
• 请求时间（UTC，精确到分钟）
• 请求 endpoint（如 /v1/chat/completions）
• 模型名
• HTTP 状态码 + 完整响应体（去掉 Key）

我们会根据网关日志（保留 30 天）定位问题。