錯誤碼
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 | 這個功能尚未開放。 |