API-Fehler

Auf dieser Seite finden Sie eine Referenz für 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 Pflichtfeld fehlt. Informationen zum Anfrageformat, Beispiele und unterstützte Versionen finden Sie in der API-Referenz. Wenn Sie Funktionen einer neueren API-Version mit einem älteren Endpunkt verwenden, kann das 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 stellen eine Anfrage in einer Region, in der das kostenlose Kontingent nicht unterstützt wird, und haben die Abrechnung für Ihr Projekt in Google AI Studio nicht aktiviert. Wenn Sie die Gemini API verwenden möchten, müssen Sie ein kostenpflichtiges Abo über Google AI Studio einrichten.
402 RESOURCE_EXHAUSTED Ihr Vorauszahlungsguthaben ist aufgebraucht. Ihr Rechnungskonto hat keine Prepay-Guthaben mehr. Daher funktionieren alle API-Schlüssel, die mit diesem Rechnungskonto verknüpft sind, nicht mehr. Fügen Sie Ihrem Rechnungskonto Guthaben hinzu oder aktivieren Sie das automatische Aufladen. Wiederholen Sie diese Anfrage nicht. Sie kann erst erfolgreich ausgeführt werden, wenn Guthaben hinzugefügt wurde.
403 PERMISSION_DENIED Ihr API-Schlüssel hat nicht die erforderlichen Berechtigungen. Sie verwenden den falschen API-Schlüssel oder versuchen, ein abgestimmtes Modell zu verwenden, ohne die richtige Authentifizierung durchzuführen. Prüfen Sie, ob Ihr API-Schlüssel festgelegt ist und die richtigen Zugriffsrechte hat. Außerdem müssen Sie sich richtig authentifizieren, um abgestimmte Modelle verwenden zu können.
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 (RPM, TPM, RPD, Ausgaben usw.). Sie senden zu viele Anfragen, verwenden zu viele Tokens oder überschreiten die ausgabenbasierten Limits für den Abrechnungsverlauf und die Stufe Ihres Kontos. Prüfen Sie, ob Sie die Ratenbeschränkungen 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 ABGEBROCHEN Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer. Der Client hat die Verbindung geschlossen, bevor die API die Antwort fertigstellen 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. Der Kontext Ihrer Eingabe ist zu lang. Prüfen Sie auf der Statusseite der Gemini API, ob es aktuelle Vorfälle gibt. 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 es funktioniert. Warten Sie etwas und versuchen Sie es dann noch einmal. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte in Google AI Studio über den Button Feedback geben.
503 UNAVAILABLE Möglicherweise ist der Dienst vorübergehend überlastet oder nicht erreichbar. Der Dienst hat vorübergehend keine Kapazitäten mehr. Prüfen Sie auf der Statusseite der Gemini API, ob es aktuelle Vorfälle gibt. 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 es funktioniert. Warten Sie etwas und versuchen Sie es dann noch einmal. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte in Google AI Studio über den Button Feedback geben.
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 ein längeres Zeitlimit fest, um diesen Fehler zu vermeiden.

Format der Fehlerantwort

Wenn eine GenerateContent-Anfrage fehlschlägt, legt die API den HTTP-Statuscode (z. B. 400 Bad Request, 403 Forbidden oder 429 Too Many Requests) fest 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