API-Fehler

Auf dieser Seite finden Sie eine Referenz zu Backend-Fehlercodes, die von der GenerateContent API zurückgegeben werden. Außerdem wird das gRPC-Fehlerantwortformat beschrieben und es werden Schritte zur Fehlerbehebung bereitgestellt.

HTTP-Fehlercodes

In der folgenden Tabelle sind häufige Backend-Fehlercodes, Erklärungen zu ihren Ursachen und empfohlene Lösungen aufgeführt:

HTTP-Code Status Beschreibung Beispiel Lösung
400 INVALID_ARGUMENT Der Anfragetext ist fehlerhaft. Ihre Anfrage enthält einen Tippfehler oder ein erforderliches Feld fehlt. In der API-Referenz finden Sie Informationen zum Anfrageformat, Beispiele und unterstützte Versionen. Die Verwendung von Funktionen aus einer neueren API-Version mit einem älteren Endpunkt kann zu Fehlern führen.
400 FAILED_PRECONDITION Die kostenlose Stufe der Gemini API ist in Ihrem Land nicht verfügbar. Aktivieren Sie die Abrechnung für Ihr Projekt in Google AI Studio. Sie senden eine Anfrage in einer Region, in der die kostenlose Stufe nicht unterstützt wird, und Sie haben die Abrechnung für Ihr Projekt in Google AI Studio nicht aktiviert. Wenn Sie die Gemini API verwenden möchten, müssen Sie in Google AI Studio einen kostenpflichtigen Plan einrichten.
403 PERMISSION_DENIED Ihr API-Schlüssel hat nicht die erforderlichen Berechtigungen. Sie verwenden den falschen API-Schlüssel oder versuchen, ein optimiertes Modell zu verwenden, ohne die entsprechende Authentifizierung durchzuführen. Prüfen Sie, ob Ihr API-Schlüssel festgelegt ist und die richtigen Zugriffsberechtigungen hat. Außerdem müssen Sie die entsprechende Authentifizierung durchführen, um optimierte Modelle zu verwenden.
404 NOT_FOUND Die angeforderte Ressource wurde nicht gefunden. Eine in Ihrer Anfrage referenzierte Bild-, Audio- oder Videodatei wurde nicht gefunden. Prüfen Sie, ob alle Parameter in Ihrer Anfrage für Ihre API-Version gültig sind.
429 RESOURCE_EXHAUSTED Sie haben eines der Ratenlimits der API überschritten (Anfragen pro Minute, Tokens pro Minute, Anfragen pro Tag, Ausgaben usw.). Sie senden zu viele Anfragen, verwenden zu viele Tokens oder überschreiten ausgabenbasierte Limits für den Abrechnungsverlauf und die Stufe Ihres Kontos. Prüfen Sie, ob Sie die Ratenlimits des Modells einhalten. Warten Sie kurz und versuchen Sie es dann noch einmal. Reduzieren Sie die Rate oder Größe Ihrer Anfragen. Fordern Sie bei Bedarf eine Erhöhung des Ratenlimits an.
499 CANCELLED Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer. Der Client hat die Verbindung geschlossen, bevor die API die Antwort senden konnte. Prüfen Sie, ob Ihre Client- oder Netzwerkinfrastruktur die Verbindung vorzeitig schließt (z.B. aufgrund eines clientseitigen Timeouts).
500 INTERN Bei Google ist ein unerwarteter Fehler aufgetreten. Ihr Eingabekontext ist zu lang. Auf der Statusseite der Gemini API finden Sie Informationen zu laufenden Vorfällen. Reduzieren Sie den Eingabekontext oder wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 2.5 Pro zu Gemini 2.5 Flash) und prüfen Sie, ob das Problem dadurch behoben wird. Alternativ können Sie auch etwas warten und die Anfrage noch einmal senden. Wenn das Problem nach dem Wiederholen weiterhin besteht, melden Sie es über die Schaltfläche Feedback senden in Google AI Studio.
503 UNAVAILABLE Der Dienst ist möglicherweise vorübergehend überlastet oder nicht verfügbar. Der Dienst hat vorübergehend nicht genügend Kapazität. Auf der Statusseite der Gemini API finden Sie Informationen zu laufenden Vorfällen. Wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 2.5 Pro zu Gemini 2.5 Flash) und prüfen Sie, ob das Problem dadurch behoben wird. Alternativ können Sie auch etwas warten und die Anfrage noch einmal senden. Wenn das Problem nach dem Wiederholen weiterhin besteht, melden Sie es über die Schaltfläche Feedback senden in Google AI Studio.
504 DEADLINE_EXCEEDED Der Dienst kann die Verarbeitung nicht innerhalb der Frist abschließen. Ihr Prompt (oder Kontext) ist zu groß, um rechtzeitig verarbeitet zu werden. Legen Sie in Ihrer Clientanfrage einen längeren Timeout fest, um diesen Fehler zu vermeiden.

Format der Fehlerantwort

Wenn eine GenerateContent-Anfrage fehlschlägt, legt die API den HTTP-Statuscode fest (z. B. 400 Bad Request, 403 Forbidden oder 429 Too Many Requests) und gibt einen JSON-Antworttext mit gRPC-Statusdetails zurück:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Feld Typ Beschreibung
code integer Der HTTP-Statuscode.
message String Eine für Menschen lesbare Beschreibung des Fehlers.
status String Der gRPC-Statuscode in SCREAMING_CASE.
details Array Zusätzlicher Fehlerkontext, z. B. ErrorInfo oder LocalizedMessage.

Nächste Schritte