响应格式
所有 API 响应均使用统一的 JSON 封套格式：{
"code": 0,
"message": "success",
"data": { ... }
}
| 字段 | 说明 |
|---|---|
code | 业务错误码。0 表示成功，非零表示具体错误 |
message | 人可读的错误描述 |
data | 成功时返回的业务数据，失败时为 null |
HTTP 状态码
HTTP 状态码与业务错误码是两个维度。袋袋的映射规则：| HTTP 状态码 | 含义 | 典型场景 |
|---|---|---|
200 | 成功 | 正常业务响应 |
400 | 请求错误 | 参数校验失败、无效操作 |
401 | 未认证 | Token 过期或无效 |
403 | 无权限 | 账号被禁、余额不足、配额用尽 |
404 | 未找到 | 资源不存在 |
409 | 状态冲突 | 重复操作（如订单已支付） |
429 | 请求过多 | 频率限制触发 |
500 | 服务器错误 | 内部异常 |
503 | 服务不可用 | 服务暂时不可用 |
5 位数业务码（如
40004）会按首位归类到对应 HTTP 状态码段：4xxxx → 400，5xxxx → 500。业务错误码一览
认证与安全
| 错误码 | 名称 | 说明 |
|---|---|---|
400 | CODE_INVALID | 验证码错误或已过期 |
403 | ACCOUNT_DISABLED | 账号已被禁用 |
400 | CAPTCHA_FAILED | 人机校验失败 |
429 | SMS_TOO_FREQUENT | 验证码发送过于频繁 |
500 | SMS_SEND_FAILED | 短信发送失败 |
401 | AGENT_TOKEN_INVALID | Agent Token 无效 |
文件与存储
| 错误码 | 名称 | 说明 |
|---|---|---|
404 | FILE_NOT_FOUND | 文件不存在 |
500 | FILE_UPLOAD_FAILED | 文件上传失败 |
500 | FILE_DOWNLOAD_FAILED | 文件下载失败 |
400 | FILE_TYPE_NOT_ALLOWED | 不允许上传该类型的文件 |
400 | FILE_TYPE_MISMATCH | 文件类型与后缀名不匹配 |
400 | FILE_SIZE_EXCEEDED | 文件大小超出限制 |
403 | STORAGE_QUOTA_EXCEEDED | 云盘空间不足，请升级套餐 |
积分与消费
| 错误码 | 名称 | 说明 |
|---|---|---|
400 | CONSUME_TYPE_INVALID | 消费类型无效 |
400 | CONSUME_PARAM_MISSING | 消费参数缺失 |
400 | CONSUME_MODEL_RATE_ZERO | 该模型不支持此计费模式 |
400 | CONSUME_BALANCE_INSUFFICIENT | 积分不足，请充值 |
400 | CONSUME_BALANCE_OVERDRAFT | 积分账户已透支 |
500 | CONSUME_DEDUCT_FAILED | 积分扣除失败 |
403 | CONSUME_ORG_QUOTA_EXCEEDED | 本月团队配额已用完 |
403 | CREDIT_ACCOUNT_FROZEN | 积分账户已冻结 |
400 | CREDIT_BALANCE_INSUFFICIENT | 积分不足 |
充值
| 错误码 | 名称 | 说明 |
|---|---|---|
400 | RECHARGE_PLAN_NOT_FOUND | 充值套餐不存在 |
500 | RECHARGE_PLANS_NOT_CONFIGURED | 充值套餐未配置 |
400 | RECHARGE_AMOUNT_INVALID | 充值金额不在允许范围 |
400 | RECHARGE_PARAM_CONFLICT | planId 和 customAmount 只能传一个 |
429 | RECHARGE_TOO_MANY_PENDING | 待支付的充值订单过多 |
403 | RECHARGE_REQUIRES_PAID_SUBSCRIPTION | 须先订阅会员套餐才能购买加油包 |
403 | RECHARGE_TEAM_ADMIN_ONLY | 团队积分由管理员统一充值 |
订阅与套餐
| 错误码 | 名称 | 说明 |
|---|---|---|
404 | SUBSCRIPTION_NOT_FOUND | 当前没有有效订阅 |
400 | SUBSCRIPTION_INVALID_PLAN | 无效的套餐代码 |
400 | SUBSCRIPTION_CANNOT_DOWNGRADE | 不支持降级套餐 |
400 | SUBSCRIPTION_ALREADY_ACTIVE | 已有有效套餐，请走升级流程 |
400 | TEAM_ALREADY_IN_ORG | 已加入团队，无法重复开通 |
400 | TEAM_SUBJECT_UNAVAILABLE | 无法切换到团队，请先加入或开通 |
403 | TEAM_LICENSE_EXPIRED | 团队版已到期 |
支付
| 错误码 | 名称 | 说明 |
|---|---|---|
404 | PAY_ORDER_NOT_FOUND | 支付订单不存在 |
400 | PAY_ORDER_EXPIRED | 支付订单已过期 |
400 | PAY_ORDER_ALREADY_PAID | 订单已支付，请勿重复付款 |
500 | PAY_CREATE_FAILED | 创建支付订单失败 |
400 | PAY_CHANNEL_NOT_SUPPORTED | 不支持的支付渠道 |
礼品卡
| 错误码 | 名称 | 说明 |
|---|---|---|
40004 | GIFT_CARD_CODE_NOT_FOUND | 卡密不存在 |
40005 | GIFT_CARD_CODE_INVALID | 卡密无效 |
40006 | GIFT_CARD_CODE_ALREADY_REDEEMED | 该卡密已被兑换 |
40007 | GIFT_CARD_CODE_EXPIRED | 卡密已过期 |
40008 | GIFT_CARD_CODE_FROZEN | 卡密异常，请联系客服 |
40010 | GIFT_CARD_BATCH_EXHAUSTED | 该批次礼品卡已全部领完 |
40011 | GIFT_CARD_BATCH_CLAIM_LIMIT | 已达到本批次领取上限 |
发票
| 错误码 | 名称 | 说明 |
|---|---|---|
400 | INVOICE_ORDER_NOT_PAID | 该订单尚未支付 |
400 | INVOICE_ORDER_EXPIRED | 已超过 60 天开票期限 |
400 | INVOICE_ALREADY_EXISTS | 该订单已申请过发票 |
400 | INVOICE_PROFILE_INCOMPLETE | 请先完善发票信息 |
400 | INVOICE_CANCEL_NOT_ALLOWED | 只有待处理的发票可以撤回 |
Skill 与应用
| 错误码 | 名称 | 说明 |
|---|---|---|
404 | SKILL_NOT_FOUND | Skill 不存在 |
400 | SKILL_OFFLINE | Skill 已下架 |
404 | APP_NOT_FOUND | 关联应用不存在 |
404 | API_KEY_NOT_FOUND | API Key 不存在 |
任务
| 错误码 | 名称 | 说明 |
|---|---|---|
404 | TASK_NOT_FOUND | 任务不存在 |
403 | TASK_ACCESS_DENIED | 无权访问该任务 |
400 | TASK_ALREADY_SUBMITTED | 任务已提交，不可重复操作 |
400 | TASK_INPUT_EMPTY | 至少需要提供一项入参 |
409 | TASK_ALREADY_PAID | 任务已支付 |
400 | TASK_PAY_INSUFFICIENT | 积分不足以支付该任务 |
基础设施
| 错误码 | 名称 | 说明 |
|---|---|---|
503 | SERVICE_UNAVAILABLE | 服务暂时不可用 |
500 | SMS_CLIENT_INIT_FAILED | 短信客户端初始化失败 |
500 | CAPTCHA_CLIENT_INIT_FAILED | 验证码客户端初始化失败 |
错误处理建议
1
检查 code 字段
响应
code 为 0 即成功。非零时检查 message 获取错误描述。2
处理 HTTP 状态码
401：刷新 Token 或重新登录429：添加退避重试逻辑5xx：服务端异常，稍后重试
3
使用错误名称做分支
在代码中使用错误名称（如
CONSUME_BALANCE_INSUFFICIENT）而非错误码数字做条件分支，增强可读性。不要依赖
message 字段做程序逻辑判断——错误消息可能随版本更新而调整措辞。始终使用 code 数字或错误名称。