エラーとデバッグ

​

エラーレスポンスの例

{
  "generation_id": "G-abc123",
  "status_code": 502,
  "error": "upstream_error",
  "error_type": "system",
  "error_origin": "upstream",
  "reason": "all_candidates_failed",
  "description": "Provider \"google-ai-studio\" failed with HTTP 403 for endpoint \"responses\" on model \"google/gemini-2.5-pro\".",
  "attempt_count": 1,
  "failed_providers": ["google-ai-studio"],
  "failed_statuses": [403],
  "provider_failure_diagnostics": {
    "category": "provider_access_missing",
    "hint": "The provider account appears not to have access to this model or feature yet. Verify account entitlements and provider-side access.",
    "provider": "google-ai-studio"
  },
  "upstream_error": {
    "code": "PERMISSION_DENIED",
    "message": "The caller does not have permission.",
    "description": null,
    "param": null
  },
  "failure_sample": [
    {
      "provider": "google-ai-studio",
      "type": "upstream_non_2xx",
      "status": 403,
      "upstream_error_code": "PERMISSION_DENIED",
      "upstream_error_message": "The caller does not have permission.",
      "upstream_error_description": null,
      "upstream_error_param": null,
      "upstream_payload_preview": "{\"error\":{\"status\":\"PERMISSION_DENIED\"}}",
      "retryable": false
    }
  ]
}

​

常に含まれるフィールド

• generation_id: サポートに共有できる安定したリクエスト ID。
• status_code: HTTP ステータスコードと同じ値。
• error: validation_error などの機械可読なエラーコード。
• error_type: 通常 user または system の大分類。
• error_origin: 主な原因が呼び出し元、Phaseo、上流プロバイダーのいずれかを示します。
• description: 発生した内容を平易に説明します。
• details（任意）: リクエスト検証エラーの構造化された詳細。

​

追加で表示されるフィールド

• reason: all_candidates_failed や pricing_not_configured など、より具体的な理由。
• provider_candidate_diagnostics と provider_enablement: 指定されたエンドポイントでモデルを使用できなかった理由。
• routing_diagnostics: ルーティングや可用性チェックで候補が絞り込まれた詳細。
• provider_failure_diagnostics: 認証情報やアクセスの不足、地域制限、レート制限など、プロバイダー側の失敗に関するヒント。
• upstream_error と failure_sample: リクエストがプロバイダーまで届いた場合に、最初のプロバイダーエラーを可能な範囲で要約します。
• failed_providers、failed_statuses、attempt_count: 再試行とフェイルオーバーに関する追加情報。

​

ステータスクラスの見方

​

よくあるエラーコード

​

プロバイダーのエラー

• provider_failure_diagnostics.category
• provider_failure_diagnostics.hint
• provider_failure_diagnostics.provider

• credentials_not_configured
• credentials_invalid_or_forbidden
• provider_access_missing
• region_or_project_restriction
• model_unavailable_for_endpoint
• rate_limited
• server_error

​

モデルまたはエンドポイントが利用できない場合

• provider_candidate_diagnostics
• provider_enablement
• missing_pricing_providers
• routing_diagnostics

• 既知だが、まだ有効になっていないモデル
• 要求されたエンドポイントに対応していないモデル
• 料金データの不足
• ロールアウトまたは内部可用性の制限

• provider_candidate_diagnostics.totalProviders: エンドポイントのフィルタリング前に、そのモデルで認識されていたプロバイダーの数。
• provider_candidate_diagnostics.supportsEndpointCount: 要求されたエンドポイントに対応するプロバイダーの数。
• provider_candidate_diagnostics.candidateCount: アダプターの確認後に残ったプロバイダーの数。
• provider_candidate_diagnostics.droppedUnsupportedEndpoint: そのエンドポイントに対応していないため除外されたプロバイダー。
• provider_candidate_diagnostics.droppedMissingAdapter: そのエンドポイント用の Gateway アダプターがまだ存在せず、除外されたプロバイダーとエンドポイントの組み合わせ。
• provider_enablement.capability: video_generation など、適用される機能ゲート。
• provider_enablement.providersBefore / provider_enablement.providersAfter: 機能または有効化フィルター適用前後のプロバイダー。
• provider_enablement.dropped[].reason: pricing_missing などの機械可読な理由。
• routing_diagnostics.filterStages[].stage: 機能、ロールアウト、ルーティング状態などのルーティング段階。
• routing_diagnostics.filterStages[].beforeCount / routing_diagnostics.filterStages[].afterCount: 各段階の前後に残ったプロバイダー数。
• routing_diagnostics.filterStages[].droppedProviders[].reason: ロールアウトやルーティングの制限などの機械可読な理由。

​

例

{
  "generation_id": "G-unsupported123",
  "status_code": 400,
  "error": "unsupported_model_or_endpoint",
  "description": "No provider is currently routable for endpoint \"responses\" on model \"example/model\".",
  "provider_candidate_diagnostics": {
    "totalProviders": 3,
    "supportsEndpointCount": 2,
    "candidateCount": 1,
    "droppedUnsupportedEndpoint": ["provider-a"],
    "droppedMissingAdapter": [
      {
        "providerId": "provider-b",
        "endpoint": "responses"
      }
    ]
  },
  "provider_enablement": {
    "capability": "responses",
    "providersBefore": ["provider-b", "provider-c"],
    "providersAfter": ["provider-c"],
    "dropped": [
      {
        "providerId": "provider-b",
        "reason": "pricing_missing"
      }
    ]
  },
  "routing_diagnostics": {
    "filterStages": [
      {
        "stage": "provider_routing_status",
        "beforeCount": 1,
        "afterCount": 0,
        "droppedProviders": [
          {
            "providerId": "provider-c",
            "reason": "provider_status_not_ready"
          }
        ]
      }
    ]
  }
}

​

任意のデバッグモード

{
  "debug": {
    "enabled": true,
    "return_upstream_request": true,
    "return_upstream_response": false,
    "trace": true,
    "trace_level": "summary"
  }
}

• enabled
• return_upstream_request
• return_upstream_response
• trace
• trace_level（summary または full）

​

再試行の方針

• **429 以外の 400 番台のエラー：**再試行する前に、リクエスト、認証情報、またはアクセスポリシーを修正してください。
• 429: 指数バックオフを実装し、Retry-After ヘッダーに従います。
• **500 番台のエラー：**操作を安全に繰り返せる場合に限り、上限を設けて再試行してください。結果が不明な送信でも、すでにジョブが作成されたり料金が発生したりしている可能性があります。受け付け済みのジョブは、再送信せずに取得してください。

​

ストリーミング固有の注意点

• ストリーミング開始前に失敗すると、通常の JSON エラーペイロードが返されます。
• ストリームの途中で失敗した場合は、部分的なストリームを未完了として扱い、再試行を提案します。
• 必ず generation_id とエンドポイント、モデルのメタデータをログに記録します。

​

トラブルシューティングのヒント

• Gateway のステータスページで進行中のインシデントを確認します。
• リクエスト本文をエンドポイントのドキュメントと照合します。
• サポートに連絡する際は generation_id を共有してください。

​

関連リソース