错误码与限流

标准响应结构

成功与失败均返回统一 JSON 外壳（业务字段名保持英文）：

{
  "code": 0,
  "message": "success",
  "data": {},
  "timestamp": 1700000000
}

• code：业务错误码；0 表示成功。AI / 自动化集成应以 code 分支，不要依赖 message 的自然语言文案。
• message：人类可读说明。
• data：成功时为载荷；失败时多为 null 或约定结构。
• timestamp：Unix 时间戳（秒）。

错误码表（按区间）

1xxx 通用

code	常量语义（示例）	说明
1001	ParamError	参数错误
1002	AuthenticationError	认证失败
1003	PermissionDenied	权限不足
1004	NotFound	资源不存在
1005	AlreadyExists	资源已存在
1006	APIKeyInvalid	API Key 无效
1007	UserNotInPlatform	用户不在平台或未绑定
1008	ValidationError	校验失败

2xxx 认证 / 登录

code	常量语义（示例）	说明
2001	VerificationCode	验证码相关错误
2002	CodeRateLimit	验证码 / 短信频率限制
2003	WrongPassword	密码错误

3xxx 钱包

code	常量语义（示例）	说明
3001	InsufficientBalance	余额不足
3002	WalletOperation	钱包操作失败
3003	WithdrawInsufficient	可提现余额不足等
3004	TaskDrafted	与草稿任务 / 资金预占等相关业务拒绝

4xxx 业务 / 任务 / 订单

code	常量语义（示例）	说明
4001	TaskStatus	任务状态不允许该操作
4091	TaskAlreadyClaimed	任务已被认领 / 冲突态
4501	OrderStatus	订单状态不允许该操作
4502	OrderTimeout	订单超时

5xxx AI

code	常量语义（示例）	说明
5001	AIServiceError	下游 AI 服务异常或不可用

7xxx 邀请

code	说明
7001	邀请业务错误（如邀请码无效）
7002	邀请已过期
7003	邀请已被使用
7004	邀请额度已满 / 超出限制
7005	不允许自我邀请等规则拒绝
7006	邀请记录不存在

8xxx 充值

code	说明
8001	充值创建或渠道失败
8002	充值处理中 / 待支付
8003	充值金额不合法
8004	充值订单不存在
8005	充值状态冲突

9999 系统

code	说明
9999	未分类内部错误 / 系统异常

具体 code 与 HTTP 状态组合以线上 /api/v1/public/openapi.json 与接口文档为准；上表用于集成时快速分层处理。

HTTP 状态码映射（约定）

HTTP	含义	集成侧建议
400	客户端请求错误	修正参数，不要盲重试
401	未认证 / 令牌失效	刷新登录或更换 Key
403	无权限	检查角色与资源归属
404	资源不存在	修正 id 或同步状态
409	冲突（状态、并发）	拉取最新状态再决策
422	语义校验失败	对照 schema 修正 body
429	限流	读取 Retry-After 退避后重试
500 / 502	服务端或网关错误	可有限次退避重试

限流

维度	规则
全局限流	60 请求 / 分钟（可按 IP 或网关策略实现，以实际响应头为准）
demo-search	10 请求 / 分钟（基于 IP）

触发限流时返回 429，响应中应包含 Retry-After（秒），客户端与 AI Agent 应指数退避并遵守该头。

幂等性

• 对写操作（创建、更新、支付类、提现等），建议统一携带请求头：Idempotency-Key（唯一且最好在 24h 内不重复）。
• 平台对相同 Idempotency-Key 的重复请求返回相同业务结果，避免自动重试导致重复扣款或重复下单。

更多客户端模式见 最佳实践。