错误码与限流

错误结构

平台错误统一返回这种结构：

{ "error": { "type": "<错误码>", "message": "<说明>" } }

排障时，请记录响应头里的 X-TT-Request-ID，凭它可在控制台「请求」页定位单条调用的计费和错误详情。

常见错误码

HTTP	type	含义	处理
401	unauthorized	API Key 缺失或无效	检查 Authorization 头、Key 是否正确 / 被禁用
402	billing_shortfall	钱包余额不足	去 充值
402	api_key_quota_exceeded	超出该 Key 的月额度	调高额度，或用别的 Key
403	model_not_allowed	模型不在该 Key 的 scope 内	调整 Key scope，或换允许的模型
403	ip_not_allowed	来源 IP 不被允许	调整 Key 的 IP 限制 / 来源
404	—	路径不存在	检查 Base URL 的 /v1 是否多 / 少；模型路径是否拼对
429	rate_limited	触发限流	按 Retry-After 重试
5xx	—	服务暂时异常	稍后重试；持续失败带 request id 联系客服

错误信息

调用失败时，平台会返回结构化错误。message 里通常包含可读原因；type 用于程序判断。可重试类错误建议带退避重试。

限流

触发限流时返回 429，并带以下响应头：

响应头	含义
Retry-After	建议多少秒后重试
X-RateLimit-Limit	每分钟请求上限
X-RateLimit-Remaining	当前窗口剩余可用次数
X-RateLimit-Reset	配额重置的时间

建议：客户端实现指数退避（exponential backoff），优先尊重 Retry-After。

不计费的情况

• 鉴权失败（401）、限流（429）、参数错误等在请求被真正处理前被拦下的请求，不扣费。
• 任务失败 / 取消 / 过期不扣费，冻结释放。
• 流式请求即使中途断开，也会尽量按真实用量结算，详见 充值与计费。

还是定位不了？

带上以下信息找客服，可快速定位：

1. X-TT-Request-ID（响应头）。
2. 大致时间、用的模型、接口路径。
3. 完整的错误响应体（error.type + message）。