錯誤
Starmodel 閘道的每個錯誤都會回傳結構化 JSON，帶有穩定的 code 欄位。請依 code 判斷，而非面向人的 message。
錯誤格式
所有錯誤共用同一個外層結構：
{ "error": { "code": "insufficient_credits", "message": "Insufficient credits. Please top up and try again.", "type": "error" }}相容 Anthropic 的 /v1/messages 接口則回傳 Anthropic 自身的錯誤結構——頂層 type: "error"，內嵌一個含 type 與 message 的 error 物件。
常見錯誤
| 狀態碼 | 錯誤碼 | 含義 |
|---|---|---|
401 | unauthorized | 缺少、無效或已被停用的 API Key。 |
403 | model_not_allowed | 該 API Key 無權呼叫所請求的模型。 |
400 | invalid_model | model 不是已知的模型 id。 |
400 | no_available_channel | 目前沒有可用於該模型的上游渠道。 |
402 | insufficient_credits | 錢包餘額不足以支付本次請求。 |
402 | subscription_quota_exceeded | 本計費週期的訂閱 token 配額已用盡。 |
400 | model_pricing_missing | 該模型尚未發布銷售價，暫時無法計費。 |
429 | rpm_exceeded | 超出每分鐘請求數上限。 |
429 | tpm_exceeded | 超出每分鐘 token 數上限。 |
429 | concurrency_exceeded | 並行請求過多。 |
502 | upstream_error | 上游服務商回傳了錯誤。 |
500 | internal | 閘道意外錯誤——請重試，若持續出現請聯絡支援。 |
限流與重試
429 回應會帶 Retry-After 標頭（單位秒）——請等待該時長後再重試。rpm_exceeded / tpm_exceeded 分別是每分鐘請求數 / token 數上限；concurrency_exceeded 表示同時進行的請求過多。
計費與定價
402 表示錢包餘額不足以支付本次請求——請儲值（insufficient_credits）或等待下個計費週期（subscription_quota_exceeded）。400 的 model_pricing_* / model_not_billable 表示該模型尚未上架銷售價；請聯絡管理員設定並發布定價。
錯誤處理
用 error.code 做程式分支——它是穩定的。error.message 面向人，可能變動。429 與 502 可退避後重試；4xx 的計費或驗證類錯誤在未修改請求前不要重試。