錯誤代碼

錯誤代碼

錯誤回應格式

錯誤 envelope 依端點而異。若有 error.type，請搭配 HTTP 狀態碼判斷；error.code 可能是字串或數字狀態碼，也可能省略；error.message 僅供顯示。

{
  "error": {
    "message": "Insufficient credits. Please top up to continue.",
    "type": "invalid_request_error",
    "code": "insufficient_credits"
  }
}

HTTP 狀態與 error.code

錯誤 envelope 依端點而異。若有 error.type，請搭配 HTTP 狀態碼判斷；error.code 可能是字串或數字狀態碼，也可能省略；error.message 僅供顯示。

機器可讀的帳務代碼

同樣是 402，也可能代表不同的帳務控制。請依下列穩定代碼顯示正確的處理方式。

詳細錯誤代碼

API 請求失敗時，error.code 會告訴你更具體的原因。即使兩個錯誤都是 HTTP 400，處理方式也可能不同：例如 unknown_model 表示模型名稱有誤，image_too_large 則表示圖片太大。請依下表找到原因與對應的處理方向。

內容審查

所有請求在送往模型端之前，都會先經過自動化內容審查。不符合使用規範的請求會被拒絕，不會送達模型，並回傳 403 錯誤。

會被攔截的內容類別

審查依據我們的使用規範（Acceptable Use Policy）進行，主要攔截以下類別的內容：

• 性剝削內容
• 暴力威脅
• 違法行為的操作指導
• 生物危害相關內容

403 回應格式

請求被審查攔截時，會收到以下格式的錯誤回應：

{
  "error": {
    "message": "Your prompt was blocked by content moderation.",
    "type": "invalid_request_error",
    "code": "content_filter"
  }
}

被攔截的請求不會計費——你不會為被拒絕的請求付費。

誤判申訴

如果你認為某次請求被誤判攔截，請聯繫支援團隊並附上請求時間與（如方便的話）request id，我們會協助複查。

隱私說明

請求會經過自動化內容審查，最新輸入的文字與圖片可能送交第三方內容安全評分服務。

判定為違規、疑似違規、接近門檻或隨機抽樣的請求，我們可能保存其全文或前段文字，供合規舉證、爭議處理與稽核之用，不承諾固定刪除期限。

其他一般成功請求不保存提示詞與回應內容；使用 ZDR 金鑰的請求不適用前兩項。

速率限制、預算與緊急煞車

這些控制可能拒絕原本有效的請求。它們與供應商錯誤不同，也需要不同的復原方式。

錯誤 envelope 依端點而異。若有 error.type，請搭配 HTTP 狀態碼判斷；error.code 可能是字串或數字狀態碼，也可能省略；error.message 僅供顯示。

影片與媒體資源狀態

影片驗證通常回傳數字 code 400；工作不存在為 404、模型退役為 410、影片內容尚未完成為 409、影片 byte range 無效為 416。重試前請先輪詢至完成，或修正 Range 標頭。

重試策略

只有在不修改請求也可能恢復的錯誤才應重試。若有 Retry-After，請依指定秒數等待；否則使用帶 jitter 的指數退避。限制重試次數，也不要同時疊加 SDK 自動重試與手動重試。

錯誤處理

import random
import time
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
    max_retries=0,  # Avoid double retries; this example handles them.
)

RETRYABLE = {429, 502, 503, 504}

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        break
    except APIStatusError as error:
        if error.status_code not in RETRYABLE or attempt == 4:
            raise
        retry_after = error.response.headers.get("Retry-After")
        delay = (
            float(retry_after)
            if retry_after
            else min(8, 0.5 * (2 ** attempt)) + random.uniform(0, 0.25)
        )
        time.sleep(delay)

串流錯誤格式

在任何 token 串流之前發生的錯誤，會以標準 HTTP 錯誤回應（JSON body）回傳。

串流一旦開始，HTTP 回應已經是 200。用戶端必須解析每個 SSE data frame；只要出現頂層 error，或 choices[0].finish_reason === "error"，就應視為失敗且回應不完整。

若串流開始後才失敗，BazaarLink 可能送出最後一個 SSE 事件，內含頂層 error 物件，之後送出 data: [DONE]。請將此回應視為不完整，不要把部分輸出當成完成的結果。

data: {"error":{"message":"The request could not be completed.","type":"upstream_error","code":502}}

data: [DONE]

// Branch on error.code; error.type can vary by failure path.