错误码

星算 用一套统一的内部错误码,在不同协议端点下按对应协议的信封格式返回。也就是说:同一个错误,在 /v1/chat/completions 下是 OpenAI 形状,在 /v1/messages 下是 Anthropic 形状——这样各家官方 SDK 能原生解析。

错误码总表

code	HTTP	含义
BAD_REQUEST	400	请求参数错误
UNAUTHORIZED	401	API Key 无效 / 过期 / 已撤销
FORBIDDEN	403	无权限(如请求的模型不在该 Key 白名单、来源 IP 不在白名单)
INSUFFICIENT_BALANCE	402	企业钱包余额不足(含授信额度)
WALLET_FROZEN	403	钱包已冻结
WALLET_SUSPENDED	403	钱包已停用
WALLET_CLOSED	403	钱包已关闭
MODEL_NOT_FOUND	404	模型不存在 / 未启用 / 能力类型不符
MODEL_DISABLED	404	模型已禁用(对外统一 404,不暴露禁用语义)
ENDPOINT_NOT_SUPPORTED	404	模型不支持该端点
QUOTA_EXCEEDED	429	API Key 软额度超限
UPSTREAM_ERROR	502	上游服务错误
INTERNAL_ERROR	500	平台内部错误

信封按路由前缀绑定

错误信封由请求路径决定,与请求头无关(避免客户端通过增减请求头切换错误格式):

路径	信封格式
/v1/chat/completions、/v1/responses、其余 /v1/*	OpenAI
/v1/messages*	Anthropic(固定)
/v1/models	按是否带 anthropic-version 头分派 OpenAI / Anthropic
/v1beta/*	Gemini(Google)
/api/v3/*	火山(Seedance)

各协议错误信封

OpenAI

{
  "error": { "message": "...", "type": "insufficient_quota", "code": "insufficient_quota" }
}

type / code 按状态推导:400 → invalid_request_error;401 → invalid_api_key;403 → permission_denied;404 → model_not_found;429 → insufficient_quota;502 → upstream_error;504 → upstream_timeout。

Anthropic

{ "type": "error", "error": { "type": "rate_limit_error", "message": "..." } }

error.type:400/422 → invalid_request_error;401 → authentication_error;403 → permission_error;404 → not_found_error;429 → rate_limit_error;5xx → api_error。

Gemini(Google)

{ "error": { "code": 429, "message": "...", "status": "RESOURCE_EXHAUSTED" } }

注意 code 是 HTTP 整数。status:400 → INVALID_ARGUMENT;401 → UNAUTHENTICATED;403 → PERMISSION_DENIED;404 → NOT_FOUND;429 → RESOURCE_EXHAUSTED;500 → INTERNAL;502/504 → UNAVAILABLE。

火山(Seedance)

{ "error": { "code": "insufficient_quota", "message": "..." } }

注意 code 是字符串。取值:400 → invalid_request;401 → invalid_api_key;403 → permission_denied;404 → not_found;429 → insufficient_quota;502 → upstream_error;504 → upstream_timeout。

注意 code 字段语义

OpenAI 与火山的 code 都是字符串但取值不同;Gemini 的 code 是 HTTP 整数;Anthropic 顶层不带 code,改用 error.type。解析错误时请按你所用的协议字段读取,不要假设统一形状。

请求体校验失败(422)

请求体不符合 schema 时返回 422,错误信封同样按上述路由规则分派为对应协议格式。