错误码参考

所有接口的错误响应都是同一个信封:

{ "error": { "code": "rate_limited", "message": "…", "requestId": "…", "detail": { } } }

code 取值见下表(共 85 个),每个码有固定的 HTTP 状态;message 是给人看的文字,不要用它做判断;requestId 用于联系支持时定位;detail 可选,按码给出结构化补充。
分组按「面」:一个码只在某一面的接口说明里出现,就归该面;在多个面出现的归「通用」;接口说明里没有出现的归「其他」。
「可重试」按 HTTP 状态判定:429 / 502 / 503 / 504 为可重试(429 请按 Retry-After 头退避);其余状态不要用同一请求原样重试。
深链锚点为码名本身,例如 #rate_limited。

面	含义	码数
通用	在多个面的接口说明中都会出现	25
twp 协议面	tansr 自有协议 twp 的接口	22
控制面	认证、组织、应用、配置等接口	20
支付回调面	支付渠道回调	1
管理面	门户管理后台专用接口	3
其他	仅在错误码目录登记,未出现在任一接口说明中	14

通用

在多个面的接口说明中都会出现。

admin_forbidden

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	管理面凭据在场但权限不足。	—

admin_key_invalid

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	管理面凭据无效。	—

app_disabled

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	应用已被停用,其凭据不能再发起请求。	提示用户联系应用所属组织的管理员。

app_ip_denied

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	请求来源 IP 不在该应用允许的地址范围内。	—

app_key_invalid

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	应用密钥(ApiKeyId / ApiKey)无效或已轮换。	引导重新配置凭据;不要在界面回显密钥值。

bad_request

出现于:数据面、twp 协议面、控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	请求格式不合法(缺参数、类型错误或头字段坏形)。	—

conflict

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	请求与当前资源状态冲突(例如重复创建或版本不一致)。	—

content_blocked

出现于:数据面、twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	请求内容被安全审查拦截,未计费。	detail.reason 给出拦截原因,可向用户说明「内容不符合使用规范」。

egress_blocked

出现于:数据面、twp 协议面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	请求要访问的外部地址被出网策略拦截(私网、元数据地址、回环或非 HTTPS)。	—

forbidden

出现于:twp 协议面、控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	凭据有效但没有执行该操作的权限。	—

idempotency_conflict

出现于:数据面、twp 协议面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	同一幂等键被用于不同的请求载荷,或已完成的结果不可重放。	—

insufficient_balance

出现于:数据面、twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
402	否	账户余额不足,无法继续调用。	引导用户充值;可结合响应头中的余额信息展示。

limit_exceeded

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	超过了资源数量上限(例如密钥数、成员数)。	—

nonce_replayed

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	签名请求的 nonce 已被使用过(重放保护)。	—

not_found

出现于:twp 协议面、控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
404	否	请求的资源不存在,或你无权看到它。	—

pay_channel_undelivered

出现于:控制面、支付回调面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	支付渠道暂不可用。	—

plan_concurrency_exceeded

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	并发会话数达到当前套餐上限。	稍后重试;长期触发应提示升级套餐。

pricing_guard_tripped

出现于:数据面、twp 协议面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	计费价格校验未通过,请求被保守拒绝。	—

quota_exceeded

出现于:数据面、twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	配额已用完(按策略包的周期上限计)。	—

rate_limited

出现于:数据面、twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	请求频率超限。	读取 Retry-After 头退避后重试。

section_not_deliverable

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该配置段不可通过远程配置下发。	—

signature_invalid

出现于:twp 协议面、控制面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	请求签名校验失败。	—

unauthorized

出现于:控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	未提供有效凭据,或令牌已被撤销 / 过期 / 无法识别。	该码使当前令牌失效:清除本地令牌并重新登录。detail.reason 取值:`revoked`、`expired`、`invalid`、`unknown_app`、`missing`、`check_unavailable`;其中 `check_unavailable` 为暂时性原因,令牌仍有效,不应清除。

upstream_error

出现于:twp 协议面、控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
502	是(退避后重试)	上游模型服务返回错误。	—

validation_failed

出现于:数据面、控制面、管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	请求参数校验失败,detail 给出具体字段。	—

twp 协议面

tansr 自有协议 twp 的接口。

asr_not_configured

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该应用尚未配置语音识别能力。	—

asr_quota_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	语音识别配额已用完。	—

context_window_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	上下文长度超过所选模型的窗口上限。	提示用户缩短输入或开启新会话。

imagegen_not_configured

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该应用尚未配置图像生成能力。	—

imagegen_quota_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	图像生成配额已用完。	—

model_not_authorized

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	当前凭据无权使用所请求的模型。	—

payload_too_large

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
413	否	请求体超过大小上限。	不可重试同一载荷;提示用户缩小内容。

plan_gate_unavailable

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	套餐守门服务暂不可用,请求被保守拒绝。	—

protocol_unsupported

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	不支持所请求的协议或协议版本。	—

session_archived

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
410	否	会话已归档,不能再续写。	—

stream_backpressure

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	流式输出背压过高,连接被服务端主动断开。	—

tts_not_configured

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该应用尚未配置语音合成能力。	—

tts_quota_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	语音合成配额已用完。	—

upstream_connect_timeout

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
504	是(退避后重试)	连接上游模型服务超时。	—

upstream_disconnected

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
502	是(退避后重试)	上游模型服务在响应过程中断开。	—

upstream_idle_timeout

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
504	是(退避后重试)	上游模型服务空闲超时(长时间无数据)。	—

upstream_total_timeout

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
504	是(退避后重试)	上游模型服务总时长超时。	—

upstream_ttfb_timeout

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
504	是(退避后重试)	上游模型服务首字节超时。	—

videogen_not_configured

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该应用尚未配置视频生成能力。	—

videogen_quota_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	视频生成配额已用完。	—

websearch_not_configured

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	该应用尚未配置联网搜索能力。	—

websearch_quota_exceeded

出现于:twp 协议面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	联网搜索配额已用完。	—

控制面

认证、组织、应用、配置等接口。

approval_self_forbidden

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	申请人不能审批自己的申请。	—

auth_channel_undelivered

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	认证通道(短信 / 邮件等)当前不可用,验证码未能送达。	—

device_code_denied

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	设备码登录被用户在门户拒绝。	—

device_code_expired

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	设备码已过期,需要重新发起登录。	—

device_code_pending

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
400	是(继续轮询)	设备码登录尚未在门户完成,请稍后继续轮询。	—

device_code_slow_down

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	设备码轮询过于频繁,请降低轮询频率。	—

envelope_key_undelivered

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	组织信封密钥服务暂不可用,无法完成加解密。	—

idp_untrusted

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	身份提供方不在组织的受信列表中。	—

invalid_api_key

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	API 密钥无效。	—

license_required

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	该能力需要有效的许可。	—

org_byok_not_available

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	组织自带密钥(BYOK)能力不可用。	—

org_ceiling_exceeded

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	超过组织设置的用量或预算上限。	—

otp_invalid

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	一次性验证码错误或已失效。	—

otp_rate_limited

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	验证码发送或校验过于频繁。	—

plan_end_users_exceeded

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
429	是(按 Retry-After 退避)	终端用户数达到当前套餐上限。	—

policy_locked

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	该设置已被组织策略锁定,不可修改。	—

pool_signing_undelivered

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	签名服务暂不可用。	—

preflight_required

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	该操作需要先通过组织治理预检。	—

principal_required

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	该操作需要人类主体(登录用户)身份,组织令牌不能代行。	—

token_expired

出现于:控制面。

HTTP 状态	可重试	说明	端侧呈现提示
401	否	令牌已过期。	刷新或重新获取令牌。

支付回调面

支付渠道回调。

pay_signature_invalid

出现于:支付回调面。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	支付回调验签失败。	—

管理面

门户管理后台专用接口。

currency_not_supported

出现于:管理面。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	不支持所请求的结算货币。	—

liquidation_not_enabled

出现于:管理面。

HTTP 状态	可重试	说明	端侧呈现提示
503	是(退避后重试)	组织清算能力未开启。	—

order_state_invalid

出现于:管理面。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	订单当前状态不允许该操作。	—

其他

仅在错误码目录登记,未出现在任一接口说明中。

adjudicator_not_authorized

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	当前主体没有作为裁决者处理该请求的权限。	—

endpoint_disabled

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	该接口当前对你的账户不可用。	—

fence_denied

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	请求被组织的资源围栏策略拒绝。	—

image_not_supported

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	所选模型不支持图片输入。	—

internal_error

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
500	否	服务端内部错误。	向用户展示 requestId,便于联系支持时定位。

model_not_found

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
404	否	请求的模型不存在或不可用。	—

pay_amount_mismatch

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	支付金额与订单金额不一致。	—

payment_required

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
402	否	该操作需要先完成支付。	—

plan_apps_exceeded

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	应用数量达到当前套餐上限。	—

plan_members_exceeded

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
400	否	组织成员数达到当前套餐上限。	—

plan_required

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	该能力需要有效套餐。	—

plan_tier_insufficient

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
403	否	当前套餐档位不包含该能力。	—

refund_not_eligible

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
409	否	该订单不满足退款条件。	—

upstream_timeout

未在任一接口说明中出现;以错误码目录为准。

HTTP 状态	可重试	说明	端侧呈现提示
504	是(退避后重试)	上游模型服务超时。	—