疑難排解

錯誤結構與你呼叫的協定保持一致。 /v1/chat/completions 和 /v1/responses 回傳 OpenAI 風格的錯誤； /v1/messages 回傳 Anthropic 風格的錯誤。三種協定的 HTTP 狀態碼完全一致。

錯誤回應格式

OpenAI 格式 (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Anthropic 格式 (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · 驗證失敗 authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

原因

• 缺少 Authorization: Bearer 請求標頭(或 X-API-Key)——訊息:missing API key in Authorization header or X-API-Key。
• 金鑰與任何有效金鑰都不相符——訊息:invalid API key。
• 金鑰已過期——訊息:API key expired。

解決

1. 傳送 Authorization: Bearer sk-syn-…(或 X-API-Key: sk-syn-…)。
2. 在主控台確認金鑰為啟用狀態,且已完整複製。

400 · 無效請求 invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

原因

• 缺少 model 欄位,或 JSON 請求主體為空或格式錯誤。

解決

1. 請提供 model 並使用格式正確的 JSON 請求主體。參見 Chat Completions 參考。

403 · 配額耗盡 quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

原因

• 金鑰或工作區的預付餘額已用完。

解決

1. 為工作區儲值。注意:餘額用盡時 Synthorai 會回傳 403 quota_exhausted,而非 429——因此指數退避無濟於事;只有儲值才能解除。

403 · 合規——不共享資料 compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

原因

• 您的工作區啟用了 no_provider_data_share,而所請求的模型僅由要求資料留存/共享的供應商提供(例如僅支援資料共享的 Bedrock 或 Vertex 模型)。

解決

1. 將請求路由到零留存模型,或在該工作負載可接受資料共享時關閉工作區合規開關。留存類別是每個模型的路由輸入項——參見 30 天資料留存詳解。

429 · 觸發速率限制 rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

原因

• 您超出了每分鐘請求上限(RPM)。訊息中會給出具體的限制值。

解決

1. 使用指數退避 + 抖動進行退避重試(見下方程式碼)。若需要持續的吞吐量,請申請更高的限制。

502 · 該模型沒有可用通道 upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

原因

• 該模型 id 在您的工作區沒有相符的可路由通道——可能是拼字錯誤、已下架的模型,或您的方案無法存取的模型。

解決

1. 對照即時模型清單核對準確的 id。如果某個模型最近已退役,請改用目前可用的模型。

BYOK:上游供應商錯誤

使用 bring-your-own-key 時,請求會在您自己的供應商帳戶上執行(AWS Bedrock、Google Vertex AI 或 Anthropic API),因此 Synthorai 會原樣透傳供應商的原始錯誤——回應中帶有 usage.is_byok: true。解決辦法在該供應商的主控台或設定中,而非閘道。最常見的是帳戶級的模型存取與資料共享設定:

上游供應商錯誤

這些錯誤由模型供應商透傳,帶有供應商自己的 HTTP 狀態碼與 type。只有 500 與 529 表示供應商側的問題;應將它們(以及 429)視為瞬時性問題並重試,而 4xx 則反映請求本身。完整參考:Anthropic 的錯誤文件。

速率限制

速率限制按 API key 強制執行，以確保所有使用者之間的公平使用。

預設限制

想根據真實的每 token 價格來規劃 token 吞吐量?用 LLM API 成本計算器跑一遍您的工作負載。

處理 429 錯誤

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

在某個模型上遇到 502 或過載?從模型價格對比中選一個備用模型——所有可路由模型及其每 token 價格盡在一張表中。