开发文档 / 通用参考
错误码与怎么办
错误统一返回下面的结构:error.message 说发生了什么,error.hint 说怎么办,request_id 可用于对账与反馈。所有错误都不扣分。
| HTTP | code | 什么时候 | 怎么办(error.hint) | 积分 |
|---|---|---|---|---|
| 400 | invalid_request | 参数错误(网关拦截或引擎判定参数错) | 看 message 里说的是哪个参数,改好再试;本次未扣积分 | 不扣 |
| 400 | operation_unavailable | 该引擎的这个接口 / 档位暂未开放 | 这个接口或档位暂未开放,换默认档或该引擎的其他接口 | 不扣 |
| 400 | invalid_code | 兑换码无效或已被使用 | 核对卡密是否抄错、是否已兑换过;仍不行请联系购买处 | — |
| 401 | unauthorized | 缺少密钥或密钥无效 | 检查请求头 Authorization: Bearer <Key>;Key 不对就回控制台重新复制 | 不扣 |
| 402 | insufficient_points | 积分不足 | 兑换新的卡密续费,同一个 Key 自动叠加;本次未扣积分 | 不扣 |
| 403 | forbidden | 账户已停用 | 账户已停用,请联系客服 | 不扣 |
| 404 | engine_not_found | 引擎不存在 | 检查引擎名是否写错,GET /v1/engines 可查看全部引擎 | 不扣 |
| 404 | endpoint_not_found | 该引擎没有这个接口 | 检查接口路径,该引擎的接口见 /docs/<引擎名> | 不扣 |
| 429 | rate_limited | 超过套餐每秒请求数(排队超过上限) | 稍等 1–2 秒再试;需要更高并发可换每秒请求数更高的套餐 | 不扣 |
| 429 | engine_busy | 引擎繁忙 | 稍等几秒再试,或用 engine 换一家 | 不扣 |
| 502 | engine_error | 引擎暂时异常(已自动重试) | 稍后重试(已自动重试过);着急可用 engine 换一家,本次未扣积分 | 不扣 |
| 503 | engine_unavailable | 引擎暂不可用或暂未开放 | 稍后再试,或用 engine 换一家已开放的引擎;本次未扣积分 | 不扣 |
| 500 | internal_error | 服务内部错误 | 稍后重试;多次出现请带上 request_id 反馈 | 不扣 |
原生接口在引擎判定参数错时,原样返回该引擎的错误结构(HTTP 400),另加 billing(本次未扣)。
错误响应
{
"error": {
"code": "insufficient_points",
"message": "积分不足:本次需要 5 积分,当前可用 3;请兑换新的卡密续费(同一个 Key 自动叠加),本次未扣积分",
"hint": "兑换新的卡密续费,同一个 Key 自动叠加;本次未扣积分"
},
"request_id": "js-20261102120000-a1b2c3d4e5f6"
}