错误码 · TokenPortal

调用失败时，平台按下面这套 code 词汇表返回错误。本页是唯一权威的对外错误码列表——code 取值一旦发布不会更改，你可以放心按它写分支判断。

本页只覆盖 code 这个字段的取值集合。信封结构（错误信息包在哪个字段里）见下方「两种信封」。

一、稳定性承诺

元素	能否变
`code` 取值	不会——一旦发布就不再更改，你可以据此写分支
`message` / `detail` 文案	可能改，只影响展示，不要用它做判断
HTTP 状态码	一般不改；如需改动会按破坏性变更处理
新增 `code`	随时可能发生——建议对未识别的 `code` 做兜底处理，不要求穷举

二、两种信封

调用模型走的数据面（https://intertoken.ai/v1）和管理账号走的控制面是两个不同的 API 面，错误信封形状不同：

数据面（OpenAI 兼容）：

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

控制面（账户/管理接口）：

{ "detail": "当前语言文案", "code": "invalid_credentials", "detail_en": "英文文案" }

两者信封不同，但 code 词汇表相同——按 code 判断逻辑可以跨两个面复用。

三、模型调用（数据面）

code	HTTP	说明
`missing_auth`	401	缺少 Authorization 请求头
`invalid_auth`	401	Authorization 格式非法
`invalid_api_key`	401	API Key 无效或已停用
`env_mismatch`	401	该 API Key 不适用于当前环境
`rate_limit_exceeded`	429	请求过于频繁，请按 `Retry-After` 退避重试
`upstream_error`	5xx	上游服务异常
`balance_insufficient`	402	余额不足
`org_balance_unavailable`	402	该组织尚未开通余额账户
`budget_exceeded`	402	组织预算已超限
`content_policy`	400	内容不符合内容政策
`ip_blocked`	403	IP 因多次认证失败被临时封禁
`insufficient_quota`	402	额度不足
`capability_not_supported`	404	该模型的供应商不支持该能力（如上下文缓存）
`reasoning_payload_not_transferable`	400	会话中携带的推理载荷（如 `thinking` 块）无法转发给本次实际调用的上游；见下方说明
`catalog_unavailable`	503	模型目录暂时不可用（平台侧故障，不代表你没有权限）
`tool_not_carryable`	400	提供的工具定义在当前路由下没有任何上游可以承载
`model_not_found`	404	模型不存在
`no_routable_sku`	404	模型存在，但此刻没有可用的供应商
`plan_paused_distributor`	402	套餐因销售方经营账户暂停而不可用
`content_not_supported`	400	当前路由到的货源不接受这次请求携带的媒体类型/形状
`asset_type_mismatch`	400	引用的平台素材实际类型与请求中声明的类型不符（例如把图片素材当视频引用）
`asset_model_mismatch`	400	引用的平台素材没有绑定到本次请求的模型
`bad_request`	400	请求不合法
`upstream_unreachable`	502	上游不可达
`internal_error`	500/502	服务内部错误
`cancelled`	503	请求已取消（客户端在等待期间自行断开，不代表平台故障）
`service_unavailable`	503	服务暂时不可用，请重试

reasoning_payload_not_transferable：当会话历史里携带了上游签发的推理载荷（如 Anthropic 的 thinking 块）、这次请求确实开启了推理，且候选供应商全部用尽而无法找到能验证该载荷的上游时返回。这类载荷带有签名校验，平台不会伪造或用其它内容顶替，因此选择明确报错而不是静默丢弃或转发一个必然失败的请求。

四、账户与认证

code	HTTP	说明
`invalid_token`	401	令牌无效
`token_revoked`	401	令牌已被吊销
`token_stale_password`	401	密码已变更，令牌失效
`invalid_refresh_token`	401	刷新令牌无效
`refresh_token_revoked`	401	刷新令牌已被吊销
`refresh_token_stale_password`	401	密码已变更，刷新令牌失效
`invalid_credentials`	401	账号或密码错误（登录场景；与 API Key 无效是两回事，见下方说明）
`account_suspended`	403	账号已被封禁或注销
`account_deleted`	401	账号已注销
`two_factor_required`	401	需要二次验证
`email_already_registered`	409	邮箱已注册
`email_already_verified`	409	邮箱已验证
`invalid_verification_code`	400	验证码无效或已过期
`invalid_reset_token`	400	重置令牌无效或已过期
`invalid_current_password`	401	当前密码错误
`current_password_required`	400	修改已有密码需提供当前密码
`user_not_found`	404	用户不存在
`rate_limit_exceeded`	429	操作过于频繁，请稍后再试
`email_send_failed`	502	邮件发送失败，请稍后重试

invalid_credentials 与 invalid_api_key 是两个不同的码，不要混用：前者是登录账号/密码错误（用控制台的人会遇到），后者是 API Key 无效或已停用（用 SDK 调模型的人会遇到）。两者对应的下一步动作不同——改密码，还是换 Key——所以平台故意不把它们合并成一个码。

五、API Key 管理

code	HTTP	说明
`api_key_not_found`	404	API Key 不存在
`organization_not_found`	404	组织不存在
`org_membership_required`	403	你不是该组织成员，不能将其设为扣费源
`org_permission_denied`	403	你在该组织没有创建 Key 的权限
`invalid_org_id`	422	`org_id` 格式非法

六、充值

code	HTTP	说明
`order_not_found`	404	订单不存在
`payment_provider_error`	502	支付服务异常
`invalid_topup_request`	400	充值请求参数非法
`invalid_json`	400	请求体不是合法 JSON

七、SDK 接入

code	HTTP	说明
`client_key_required`	401	缺少 Client Key
`invalid_client_key_format`	401	Client Key 格式非法
`invalid_client_key`	401	Client Key 无效或已吊销
`app_not_found`	401	应用不存在或已停用
`cache_unavailable`	503	服务暂时不可用，请重试
`external_identity_claimed`	409	该外部身份已被认领，须由用户本人登录获取完整平台会话

遇到本页未列出的 code，请按未知值处理（不要因此中断集成），并欢迎反馈给我们补充登记。