> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 错误码参考
> 袋袋 API 的 HTTP 状态码与业务错误码完整对照表
## 响应格式
所有 API 响应均使用统一的 JSON 封套格式：
```json theme={null}
{
"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` | 验证码客户端初始化失败 |
## 错误处理建议
响应 `code` 为 `0` 即成功。非零时检查 `message` 获取错误描述。
* `401`：刷新 Token 或重新登录
* `429`：添加退避重试逻辑
* `5xx`：服务端异常，稍后重试
在代码中使用错误名称（如 `CONSUME_BALANCE_INSUFFICIENT`）而非错误码数字做条件分支，增强可读性。
不要依赖 `message` 字段做程序逻辑判断——错误消息可能随版本更新而调整措辞。始终使用 `code` 数字或错误名称。