错误码

Lazu 错误响应遵循 OpenAI 风格：

{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "param": "purpose",
    "request_id": "req_lazu_01ABCDEF..."
  }
}

code 是稳定的机器可读字段，程序应匹配 code 而不是 message。 request_id 也会出现在 X-Lazu-Request-Id 响应头中；联系支持时请带上它。

HTTP 状态码

状态码	类型	建议处理
200	成功	无需处理
201	文件上传成功	等同成功，部分客户端需要兼容 201
400	请求错误	修正请求 body 或参数后再试
401	鉴权失败	修正 API Key，不要盲目重试
403	禁止访问	key 被禁用、IP 不在白名单或额度耗尽
404	不存在	path、model 或 file_id 错误
413	Payload 过大	文件或引用内容超过限制
422	校验失败	body schema 正确但字段值非法
429	速率限制	按 `Retry-After` 等待后重试
500	Lazu 内部错误	指数退避重试，持续出现则联系支持
502	上游错误	可重试，Lazu 会尽量切换备用 channel
503	上游不可用	通常是临时问题，可重试
504	上游超时	可重试，并检查请求是否过慢或过大

常见错误码

鉴权

Code	含义
`invalid_api_key`	Header 缺失、格式错误、key 不存在或已删除
`insufficient_quota`	余额为零，需要充值
`ip_not_allowed`	当前请求 IP 不在 key 的白名单内
`token_disabled`	key 被手动禁用
`token_expired`	key 超过过期时间

请求格式

Code	含义
`bad_request_body`	JSON 无法解析，或上游认为请求格式错误
`missing_required_parameter`	缺少必填字段，`param` 会指出字段名
`invalid_request`	通用请求格式错误
`model_not_found`	模型不存在，或当前 key 没有访问权限
`convert_request_failed`	Lazu 无法把请求转换成目标 provider 格式
`tokenization_error`	输入 token 统计失败，通常是 prompt 过大或格式异常

Files API

Code	含义
`purpose_not_supported`	使用了尚不支持的 purpose
`file_not_found`	`file_id` 不存在或不属于当前 key
`file_expired`	文件超过 30 天保留期
`file_too_large`	单文件或 Responses 解引用总大小超限
`file_dereference_failed`	存储系统读取文件失败

计费与限额

Code	含义
`pricing_not_configured`	模型存在，但当前 lane 没有配置售卖价格
`pre_consume_token_quota_failed`	额度预扣冲突，可重试一次
`request_rate_limit_exceeded`	触发账号层级 RPM 限制
`token_rate_limit_exceeded`	触发单个 API Key 的 RPM/TPM 限制

上游与路由

Code	含义
`upstream_error`	上游返回非 2xx，`details.status_code` 是原始状态
`upstream_timeout`	上游超时
`upstream_network_error`	连接上游失败
`channel_response_time_exceeded`	单个 channel 超过响应时间预算
`no_available_channel`	没有可用 channel 服务当前模型和 lane

重试策略

状态或 code	是否重试
`429 request_rate_limit_exceeded`	是，遵守 `Retry-After`
`500` / `502` / `503` / `504`	是，指数退避，最多 3 次
`400` / `404` / `422`	否，先修正请求
`401` / `403`	否，先修正鉴权或额度
`upstream_error` 且上游是 4xx	否
`upstream_error` 且上游是 5xx	是

提交支持工单

每个成功或失败响应都会包含：

X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX

把这个 ID 放进支持工单，可以让我们直接追踪路由、上游调用和计费路径。

HTTP 状态码

常见错误码

鉴权

请求格式

Files API

计费与限额

上游与路由

重试策略

提交支持工单

相关页面