API 接口文档
错误码
TokenBay Gateway 错误响应格式、HTTP 状态码与业务异常码参考
本页定义 TokenBay Gateway 业务 API 的错误响应格式，并说明 HTTP 状态码与业务异常码的使用约定。
HTTP 状态码用于标识请求处理与服务可用性结果；具体业务失败原因以响应体中的 error.code 为准。
异步任务的执行结果与进度状态由对应接口的响应字段表达。
错误响应格式
响应
字段error.messagestringOptional面向调用方的错误说明。
error.typestringOptional错误分类。
error.codestringOptional业务异常码或协议错误码。
HTTP 状态码规约
错误
| 状态码 | 语义 | 典型场景 |
|---|---|---|
| 200 | 成功 | 任务查询成功。即使任务本身失败，也通过响应体中的 status: "failed" 表达。 |
| 400 | 客户端请求错误 | 参数无效、缺少必填字段、请求体解析失败、任务不存在。 |
| 401 | 鉴权失败 | Token 缺失或无效。 |
| 403 | 权限不足 | 用户被封禁、额度不足、无权访问分组或模型、IP 限制不通过。 |
| 404 | 资源不存在 | 未匹配路由，或视频内容代理中任务不存在。 |
| 413 | 请求体过大 | 请求体超过大小限制。 |
| 429 | 请求限流 | 模型请求限流、全局 API 限流、上游负载饱和。 |
| 500 | 服务端内部错误 | 请求转换失败、调用上游失败、响应解析失败、序列化失败。 |
| 501 | 未实现 | 接口或转换未实现。 |
| 502 | 网关错误 | 视频内容代理中上游 URL 抓取失败。 |
| 503 | 服务不可用 | 无可用渠道、系统资源过载（CPU / 内存 / 磁盘）、渠道无可用 key。 |
| 504 | 上游超时 | 渠道响应时间超限。 |
HTTP 状态码用于标识请求处理与服务可用性结果；具体业务失败原因以 error.code 返回。
业务异常码
错误
| 状态码 | 异常码 | 语义 |
|---|---|---|
| 403 | api_key_disabled | API Key 被禁用 |
| 403 | api_key_expired | API Key 已过期 |
| 403 | api_key_unavailable | API Key 状态不可用 |
| 403 | ip_denied_by_blacklist | 来源 IP 命中黑名单 |
| 403 | ip_not_in_whitelist | 来源 IP 不在白名单 |
| 403 | model_disabled | 模型已禁用 |
| 403 | model_capability_not_supported | 模型不支持当前 endpoint 能力 |
| 403 | api_key_model_not_allowed | Key 模型黑白名单不允许该模型 |
| 403 | account_point_insufficient | 账号积分余额不足 |
| 403 | api_key_point_insufficient | API Key 子额度不足 |
| 403 | access_rule_time_window_denied | 不在访问规则允许时间窗 |
| 404 | model_not_found | 模型不存在 |
| 429 | account_rate_limited | 账号请求速率超限 |
| 429 | api_key_point_limit_exceeded | API Key 周期积分上限超出 |
业务异常码通过错误响应中的 error.code 返回，用于标识具体业务失败原因，便于调用方进行分类处理。