錯誤與限制

錯誤會採用您呼叫的 API 格式：物件error用於 OpenAI， {"type": "error", "error": {...}}用於 Anthropic，以及error ，其欄位包含status與details ，用於 Gemini。因此 SDK 會將它們辨識為一般 API 錯誤。

• error.code與error.reason —下方表格中的錯誤類別，兩者相同。error.type —該格式的標準值 (例如invalid_request_error或server_error).
• error.request_id (Anthropic 使用request_id頂層欄位)，標頭X-Request-ID及訊息文字末尾，都會提供請求識別碼。
• Gemini 的錯誤類別位於error.details：ErrorInfo.reason —相同代碼的大寫形式 (例如MODEL_OVERLOADED), domain — ailoot.ai; 請求識別碼位於RequestInfo.requestId。
• 在 Gemini 格式中，不能自動重試的 5xx 錯誤，以及result_pending_check ，會以 409 狀態及status ABORTED傳回，讓 Gemini SDK與CLI 不會自行重試。錯誤類別位於ErrorInfo.reason (例如MODEL_TIMEOUT或RESULT_PENDING_CHECK).
• OpenAI 格式的回應還包含頂層欄位code與message —供舊版用戶端使用。

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

模型回應與結果檢查相關的代碼 (502、503與504)，現在會指明模型或請求：model_unavailable，model_timeout，invalid_model_response，incomplete_response，charge_not_confirmed與result_pending_check。若您的程式碼將error.code與舊值比較，請改為表格中的代碼；舊代碼與新代碼的對應關係可詢問客服。

• 先查看 X-Should-Retry：若為false，result_pending_check或model_timeout ，請勿自動重試。請在控制台歷史紀錄中查找 Request ID，其中可查看結果與扣款。
• 收到 X-Should-Retry: true 時，才可安全重試：請等待Retry-After秒。對 5xx 而言，只有狀態碼並不足夠，結果可能已經產生。請先查看控制台歷史紀錄，或提供 Request ID 聯絡客服。影像、影片、音樂與較長的代理步驟，尤其需要注意。
• 重試無法解決：400、401、402、403、404，請先修正請求、金鑰或餘額。

請求頻率與同時進行的請求數的限制，適用於整個帳戶，而非個別金鑰。超過限制時會收到 429 rate_limit_exceeded並包含標頭Retry-After: 10。若是模型本身過載，則為 503 model_overloaded包含Retry-After: 30。若需要處理更高負載，請聯絡客服。

支出限制設定於金鑰：總上限對應 402 api_key_quota_exhausted，5 小時、1 天與7 天的時間視窗對應 429 usage_limit_reached。詳細說明請見API 金鑰與位址。

即使餘額為零，也可查詢模型清單；生成則需要足夠餘額供保留金額使用。NVIDIA 模型 (Nemotron 等) 共用佇列，負載較高時，回應可能較晚抵達，或傳回「模型暫時過載」錯誤及 Retry-After 標頭，請等待指定時間後重試。價格請見目錄，扣款方式與其他模型相同。

大小限制由模型決定，包括上下文 (可傳送的 token 數)與回應的最大長度。這些資訊列於目錄。