エラーと制限

エラーは、呼び出した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キーとAPIアドレス。

モデル一覧は残高ゼロでも取得できます。生成には仮確保に必要な残高が必要です。NVIDIAモデル（Nemotronなど）は共通のキューで処理されるため、負荷が高いと応答が遅れたり、Retry-Afterヘッダー付きの「モデルが一時的に過負荷」エラーが返ったりする場合があります。指定された時間後に再試行してください。料金はカタログに記載され、残高の差し引きは他のモデルと同様です。

サイズの制限はモデルごとに定められています。コンテキスト長（送信できるトークン数）と最大出力長の記載先：カタログ。