Fehler und Debugging

​

Beispiel einer Fehlerantwort

{
  "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
    }
  ]
}

​

Felder, die immer zurückgegeben werden

• generation_id: stabile Anfrage-ID, die Sie an den Support weitergeben können.
• status_code: entspricht dem HTTP-Statuscode.
• error: maschinenlesbarer Fehlercode, z. B. validation_error.
• error_type: allgemeine Klasse, meist user oder system.
• error_origin: gibt an, ob das Problem hauptsächlich durch den Aufrufer, Phaseo oder einen Upstream-Anbieter verursacht wurde.
• description: verständliche Erklärung des Fehlers.
• details (optional): strukturierte Validierungsdetails bei einem Fehler in der Anfragevalidierung.

​

Weitere mögliche Felder

• reason: genauerer Untergrund, z. B. all_candidates_failed oder pricing_not_configured.
• provider_candidate_diagnostics und provider_enablement: erklären, warum ein Modell für den angeforderten Endpunkt nicht verwendet werden konnte.
• routing_diagnostics: zusätzliche Angaben dazu, wie Routing- oder Verfügbarkeitsprüfungen die Anfrageauswahl eingeschränkt haben.
• provider_failure_diagnostics: Hinweise zu fehlenden Zugangsdaten, Zugriffsproblemen, regionalen Einschränkungen, Ratenbegrenzungen und ähnlichen Anbieterfehlern.
• upstream_error und failure_sample: bestmögliche Zusammenfassung des ersten Anbieterfehlers, falls die Anfrage einen Anbieter erreicht hat.
• failed_providers, failed_statuses und attempt_count: zusätzlicher Kontext zu Wiederholungsversuchen und Failover.

​

Bedeutung der Statusklassen

​

Häufige Fehlercodes

​

Wenn ein Anbieter ausfällt

• 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

​

Wenn ein Modell oder Endpunkt nicht verfügbar ist

• provider_candidate_diagnostics
• provider_enablement
• missing_pricing_providers
• routing_diagnostics

• einem bekannten Modell, das noch nicht aktiv ist
• einem Modell, das den angeforderten Endpunkt nicht unterstützt
• fehlenden Preisdaten
• Einschränkungen beim Rollout oder bei der internen Verfügbarkeit

• provider_candidate_diagnostics.totalProviders: Anzahl der für das Modell bekannten Anbieter vor der Endpunktfilterung.
• provider_candidate_diagnostics.supportsEndpointCount: Anzahl der Anbieter, die den angeforderten Endpunkt unterstützen.
• provider_candidate_diagnostics.candidateCount: Anzahl der nach den Adapterprüfungen verbliebenen Anbieter.
• provider_candidate_diagnostics.droppedUnsupportedEndpoint: Anbieter, die wegen fehlender Unterstützung des Endpunkts entfernt wurden.
• provider_candidate_diagnostics.droppedMissingAdapter: Anbieter-/Endpunktpaare, die entfernt wurden, weil es noch keinen Gateway-Adapter für diesen Endpunkt gibt.
• provider_enablement.capability: geprüfte Fähigkeit, z. B. video_generation.
• provider_enablement.providersBefore / provider_enablement.providersAfter: Anbieter vor und nach der Filterung nach Fähigkeit oder Freigabe.
• provider_enablement.dropped[].reason: maschinenlesbare Gründe wie pricing_missing.
• routing_diagnostics.filterStages[].stage: Routing-Phase, z. B. Filterung nach Fähigkeit, Rollout oder Routing-Status.
• routing_diagnostics.filterStages[].beforeCount / routing_diagnostics.filterStages[].afterCount: Anzahl der Anbieter vor und nach jeder Phase.
• routing_diagnostics.filterStages[].droppedProviders[].reason: maschinenlesbare Gründe wie Rollout- oder Routing-Einschränkungen.

​

Beispiel

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Optionaler Debug-Modus

{
  "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 oder full)

​

Wiederholungsstrategie

• 400er-Fehler außer 429: Korrigieren Sie die Anfrage, Zugangsdaten oder Zugriffsrichtlinie vor einem erneuten Versuch.
• 429: Verwenden Sie exponentielles Backoff und beachten Sie den Retry-After-Header.
• 500er-Fehler: Verwenden Sie begrenzte Wiederholungsversuche nur, wenn die Wiederholung sicher ist. Eine Übermittlung mit unklarem Ergebnis kann bereits einen Job erstellt oder Kosten verursacht haben; rufen Sie einen angenommenen Job ab, statt ihn erneut zu übermitteln.

​

Hinweise speziell für Streaming

• Schlägt die Anfrage vor Beginn des Streamings fehl, erhalten Sie eine standardmäßige JSON-Fehlerantwort.
• Schlägt sie während des Streams fehl, behandeln Sie den Teilstream als unvollständig und bieten Sie einen erneuten Versuch an.
• Protokollieren Sie immer generation_id sowie Endpunkt- und Modellmetadaten.

​

Tipps zur Fehlerbehebung

• Prüfen Sie auf der Gateway-Statusseite, ob gerade eine Störung vorliegt.
• Vergleichen Sie den Anfrage-Body mit der Endpunktdokumentation.
• Geben Sie bei einer Supportanfrage die generation_id an.

​

Zugehörige Ressourcen