API 参考

状态码与故障处理

先检查 HTTP 状态，再根据业务 code 定位原因。所有错误响应都应包含可用于排查的 requestId。

2xx

请求成功

可以继续处理业务数据

4xx

请求需修正

检查认证、参数与调用频率

5xx

服务暂不可用

有限重试并保留请求标识

HTTP	业务 code	名称	说明	建议操作
200	0	请求成功	请求已完成，业务数据位于 data 字段。	继续处理返回数据
400	40001	兑换码无效	兑换码不存在、已使用或已失效。	核对兑换码后重试，或请联系平台管理员
401	40101	认证失败	未登录，或 API Key 无效、已撤销。	检查 Authorization 请求头或重新签发 Key
402	40201	积分不足	余额低于本次调用所需积分，请求未扣费。	返回 402 并引导兑换积分
403	40301	权限不足	当前账户无权访问该资源或管理接口。	更换有权限的账户后重试
404	40401	资源不存在	Skill、接口或目标资源未发布或不存在。	核对请求路径和编号
409	40901	幂等进行中	相同 idempotency_key 的请求仍在执行。	稍后用同一幂等键重试
409	40902	邮箱已注册	该邮箱已有账户。	直接登录或更换邮箱
409	40903	编辑冲突	资源已被其他会话更新。	重新加载后再保存
422	42201	参数校验失败	请求体不是对象，或缺少必填字段。	按 details 修正 JSON 后重试
429	42901	请求过快	当前时间窗口的请求数已经超过限制。	读取 Retry-After 后重试
500	50001	执行失败	云端执行失败；已受理的调用会自动等额退款。	保留 requestId，有限重试
500	50000	服务器内部错误	未分类的服务端异常。	保留 requestId 并提交工单

错误响应结构

{
  "code": 42901,
  "message": "rate limit exceeded",
  "details": { "retryAfter": 2 },
  "requestId": "req_local_8f2a"
}

故障处理顺序