首页控制台

错误码

稳定、机器可读的错误码目录。错误码永不删除或复用，HTTP 状态始终遵循语义。

目录

常见公开错误码及其 HTTP 状态，以及 SDK 是否会自动重试。

错误码	HTTP	可重试	含义
`INSUFFICIENT_CREDIT`	402	否	钱包余额低于调用所需。请充值或启用自动充值。
`WALLET_CAP_EXCEEDED`	402	否	钱包已达余额上限。请先消费，或升级套餐。
`PRO_REQUIRED`	402	否	该功能或模块需要 Pro 套餐。
`KYC_REQUIRED`	402	否	月度充值已超过需要身份验证的阈值。
`TOPUP_2FA_REQUIRED`	402	否	大额充值触发了邮箱两步验证；请携带挑战令牌与验证码重试。
`BYOK_TRIAL_EXPIRED`	402	否	30 天 BYOK 试用已结束；升级到 Pro 以继续使用自带密钥。
`UNAUTHORIZED`	401	否	缺少或无效的项目密钥。
`SCOPE_INSUFFICIENT`	403	否	项目密钥的 scope 不包含该能力。
`KEY_REVOKED`	403	否	项目密钥已被吊销；请使用新密钥。
`MODULE_NOT_AVAILABLE_IN_REGION`	403	否	该模块在当前区域 SKU 下不可用。
`IDEMPOTENCY_KEY_REQUIRED`	400	否	资源创建类调用必须包含 idempotency_key。
`IDEMPOTENCY_CONFLICT`	409	否	同一 idempotency_key 被用于不同参数。
`RATE_LIMIT_USER`	429	自动重试	已达单用户限流；请等待 Retry-After 或升级以获得更高配额。
`RATE_LIMIT_IP`	429	自动重试	已达单 IP 限流；请等待 Retry-After。
`VENDOR_QUOTA_EXCEEDED`	429	自动重试	上游供应商配额耗尽；SDK 会自动切换。
`VENDOR_DOWN`	503	自动重试	上游供应商故障且切换未成功。
`VENDOR_TIMEOUT`	503	自动重试	上游供应商超过超时；调用会被重试。
`MAINTENANCE`	503	自动重试	计划维护窗口；请等待 Retry-After。
`UNKNOWN_ERROR`	500	否	无法识别的错误码（前向兼容）；将如实暴露给你的代码。

错误处理

默认情况下，失败的调用会返回带错误的结果而非抛出异常，因此你的业务流程永不被打断。

限流与上游错误会按退避自动重试，并遵循 Retry-After 头。

已发布的错误码是永久的：其含义永不静默变更，弃用的错误码至少保留 12 个月。