错误码
Lazu 返回的每个错误都有三个稳定标识:Lazu 错误编号(LZ-3101)、code(insufficient_quota)和 type(insufficient_quota)。HTTP 状态码始终是真实的,错误不会以 200 返回。
响应结构
OpenAI 兼容接口保留 OpenAI 的错误对象,Lazu 的字段加在旁边。只认识 OpenAI 字段的 SDK 照常工作。
{
"error": {
"message": "Wallet balance is too low for this request. Top up to continue.",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_quota",
"lazu": "LZ-3101",
"docs": "https://lazu.ai/docs/errors#lz-3101",
"request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX",
"details": {}
}
}Anthropic 兼容接口(/v1/messages)使用 Anthropic 的结构和类型:
{
"type": "error",
"error": {
"type": "billing_error",
"message": "Wallet balance is too low for this request. Top up to continue.",
"code": "insufficient_quota",
"lazu": "LZ-3101",
"docs": "https://lazu.ai/docs/errors#lz-3101"
},
"request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX"
}| 字段 | 含义 |
|---|---|
code | 发生了什么。稳定,程序按它分支。 |
type | 下一步该做什么(见下表)。稳定。 |
lazu | Lazu 错误编号。稳定,联系支持时提供它。 |
message | 给开发者看的英文说明。可能调整,不要解析它。 |
param | 出问题的请求字段(如有)。 |
details | 结构化的值,例如 field、model、retry_after_seconds。 |
request_id | 这个错误所属的请求。 |
docs | 指向本页对应编号的链接。 |
每个错误响应还带有 X-Lazu-Request-Id 和 X-Lazu-Error 响应头。
错误类型
| 类型 | HTTP | 处理方式 |
|---|---|---|
invalid_request_error | 400、413 | 修正请求,原样重试没有用。 |
authentication_error | 401 | 修正 API Key:无效、过期、停用各有自己的 code。 |
permission_error | 403 | Key 或账号不允许这个操作:IP、模型、供应商或项目范围。 |
not_found_error | 404 | 路径、模型或 ID 不对。 |
insufficient_quota | 429 | 余额或某项预算用完。充值或调高预算,重试无效。 |
rate_limit_error | 429 | 等待 Retry-After 后再试。 |
content_policy_violation_error | 400 | 模型拒绝了内容,需要修改内容。 |
overloaded_error | 503 | 繁忙,稍后退避重试。 |
timeout_error | 504 | 没有及时返回,结果未知;重放前先确认。 |
api_connection_error | 502 | 连接中断,结果未知;重放前先确认。 |
api_error | 500、502 | Lazu 或模型出错。幂等请求可重试;持续出现请带请求编号联系支持。 |
在 /v1/messages 上,insufficient_quota 以 Anthropic 的 billing_error 返回,timeout_error 和 api_connection_error 以 api_error 返回。
重试策略
只在尚未收到输出、且请求可以安全重放时重试。429 要区分临时限流和 insufficient_quota:余额不足需要处理额度,不能靠重试解决。有 Retry-After 时遵循它;临时网关/上游故障采用有限次退避。执行状态不明时,SDK 自动重试可能产生另一次调用,应明确配置。网关切换渠道和客户端重试是两个决定。
流式响应
流开始后 HTTP 状态码不能再改变。Lazu 会用协议自己的错误帧结束流,帧里是同样的错误对象(Chat Completions 为 data: {"error": {...}} 加 data: [DONE],Responses 和 Messages 为 error 事件)。请保留已收到的部分输出,重放前先查看请求详情。遇到 413 request_body_too_large 请缩小请求;遇到 503 gateway_overloaded 请稍后退避重试。
提交支持工单
每个 Lazu 响应(成功或失败)都带有:
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX把它和 LZ- 编号一起贴进支持工单,我们可以追踪完整的路由、上游调用和计费过程。
错误编号速查
LZ-1xxx · 请求本身
LZ-20xx · API Key
LZ-21xx · 控制台登录状态
LZ-22xx · 登录与注册
LZ-23xx · 访问权限
LZ-26xx · 判别模型
LZ-3xxx · 钱包与预算
LZ-4xxx · 模型与线路
LZ-5xxx · 速率与容量
LZ-6xxx · 上游模型服务
LZ-7xxx · 控制台
LZ-9xxx · 内部错误
| 编号 | Code | HTTP | 类型 | 含义与处理 |
|---|---|---|---|---|
LZ-9001 | internal_error | 500 | api_error | 服务没能完成这个请求。如果反复出现,请带上请求编号联系支持。 |
LZ-9002 | not_implemented | 501 | api_error | 这个功能还没有开放。 |