Gemini API Fehler beheben: 401, 404, 429 und Regionssperren (2026)

Die Fehlermeldungen der Gemini API wirken vielfältig, lassen sich in der Praxis aber meist vier Gruppen zuordnen: falsche Identität, falsche Adresse, unzureichendes Kontingent oder ein Netz, das den Dienst nicht erreicht. Echte Modellfehler sind vergleichsweise selten.

Dieser Artikel geht die Fehlercodes einzeln durch und liefert eine Prüfreihenfolge, die mit der minimalen Anfrage beginnt. Bei Problemen zuerst die vollständige Fehler-JSON sichern und dann der Reihe nach prüfen; nicht gleichzeitig Key, Adresse und Modell ändern.

Hinweis: Google und Gemini sind Marken ihrer jeweiligen Inhaber. Der Beitrag beschreibt die übliche Schnittstellenform im Oktober 2026. Schnittstellenversion, Kontingente und Regionspolitik richten sich nach der offiziellen Dokumentation und den Modellpreisen.

1. Zuerst den Fehlerkörper lesen

Google-API-Fehler werden üblicherweise als JSON zurückgegeben; drei Felder sind entscheidend:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code ist der HTTP-Statuscode, status der maschinenlesbare Fehlertyp, message enthält oft den konkreten Grund, und details kann eine Kontingent-ID sowie einen empfohlenen Wiederholungszeitpunkt nennen. Alle drei prüfen; wer nur „429“ liest, übersieht, ob es sich um eine Minutenbegrenzung oder ein erschöpftes Tageskontingent handelt.

Statuscode	Häufiger status	Richtung
401	UNAUTHENTICATED	Key fehlt, ungültig oder an falscher Stelle
403	PERMISSION_DENIED	Projekt nicht aktiviert, Rechte oder Region eingeschränkt
404	NOT_FOUND	Modellname, Pfad oder Version falsch
429	RESOURCE_EXHAUSTED	Rate, Parallelität oder Kontingent überschritten
400	INVALID_ARGUMENT / FAILED_PRECONDITION	Parameterfehler, Region nicht unterstützt, Vorbedingung fehlt
500/503	INTERNAL / UNAVAILABLE	Vorübergehende Upstream-Störung, meist mit Backoff wiederholbar

2. 401: Key ungültig oder Authentifizierungsart falsch

Bei 401 erkennt der Server die Identität nicht an. Häufige Ursachen:

• Die Anfrage enthält keinen Key, oder die Umgebungsvariable ist leer.
• Die native Schnittstelle verwendet Authorization statt x-goog-api-key.
• Die OpenAI-kompatible Schnittstelle verwendet x-goog-api-key statt Authorization: Bearer.
• Vor oder nach dem Key stehen Leerzeichen oder Zeilenumbrüche; beim Kopieren sind Anführungszeichen mitgekommen.
• Der Key wurde gelöscht, rotiert oder das zugehörige Projekt deaktiviert.
• Ein Gateway-Key wurde an die offizielle Google-Adresse gesendet oder umgekehrt.
• Für den Key bestehen API-Einschränkungen, die Gemini ausschließen.

Zuerst mit einer minimalen Anfrage bestätigen:

export GEMINI_API_KEY="IHR_KEY"

# Native Gemini-Schnittstelle
curl "https://generativelanguage.googleapis.com/v1beta/models/<MODELL-ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Antworte nur mit OK"}]}]}'

# OpenAI-kompatible Schnittstelle
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODELL-ID>","messages":[{"role":"user","content":"Antworte nur mit OK"}]}'

Die beiden Befehle gehören zu zwei Authentifizierungssystemen. Welcher funktioniert, zeigt, zu welchem System Key und Adresse gehören. Ein 401 bei gemischter Verwendung bedeutet nicht, dass der Key defekt ist, sondern dass die Kombination nicht stimmt.

3. 404: Modellname, Pfad oder Version falsch

404 heißt nicht zwingend „Modell existiert nicht“. Häufige Fälle:

1. Die Modell-ID ist falsch geschrieben, oder es wurde der Anzeigename aus der Konsole statt der API-Bezeichner verwendet.
2. Das Modell gehört nicht zur aktuellen API-Version, etwa wenn ein nur in der neuen Version verfügbares Modell an einen alten Pfad gesendet wird.
3. Bei der Base URL fehlt oder doppelt sich /v1 beziehungsweise /v1beta, sodass der zusammengesetzte Pfad nicht existiert.
4. Am Ende der Adresse steht ein zusätzlicher Schrägstrich, und der Client hängt den Pfad erneut an.
5. Beim Aufruf über ein Gateway ist das Modell in der aktuellen Gruppe oder im Tarif nicht freigeschaltet.
6. Eine Chat-Schnittstelle wird für Bildgenerierung oder eine andere Spezialschnittstelle verwendet.

Zuerst die mit dem aktuellen Key verfügbaren Modelle auflisten:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Steht das Zielmodell in der Liste, den Anfragepfad prüfen; fehlt es, zuerst Freischaltung oder Berechtigung klären. Beim Aufruf über ein Gateway gelten die Modell-IDs und Base URL aus der Gateway-Dokumentation; offizielle Modellnamen nicht unverändert übernehmen.

4. 429: Drosselung oder aufgebrauchtes Kontingent

429 wird am häufigsten falsch gedeutet. Mindestens drei Fälle sind möglich:

Typ	Typisches Merkmal	Richtung
Minutenbegrenzung	Hohe Parallelität über kurze Zeit, Fehler innerhalb weniger Sekunden	Parallelität senken, Backoff
Tageskontingent erschöpft	Tagesvolumen erreicht, anhaltende Fehler	Auf Reset warten, Kontingent erhöhen oder Lösung wechseln
Projektkontingent	Mehrere Dienste teilen ein Projekt und konkurrieren	Projekte, Keys und Kontingente trennen

details im Fehlerkörper nennt meist Kontingent-ID und empfohlenen Wiederholungszeitpunkt. Nicht bei jedem 429 sofort erneut senden; eine Retry-Lawine verschlimmert die Lage. Zuerst die Abhängigkeit installieren: pip install requests. Eine brauchbare Backoff-Logik:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<MODELL-ID>:generateContent"
    headers = {
        "x-goog-api-key": "IHR_KEY",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("Maximale Zahl der Wiederholungen erreicht")

Wiederholungen beheben nur vorübergehende Überlastung, nicht ein erschöpftes Kontingent. In der Produktion sind zusätzlich Timeouts, Circuit Breaker und ein Ausweichmodell nötig; sonst reißt ein einzelner 429 die ganze Kette mit.

5. Regionssperren: Warum die Direktverbindung aus China scheitert

Die Gemini API ist nur in bestimmten Ländern und Regionen verfügbar. Liegt der Netzausgang in einer nicht unterstützten Region, zeigen sich drei typische Bilder:

• Verbindungs-Timeout oder TLS-Handshake-Fehler, meist wegen eines nicht erreichbaren Netzpfads.
• 400 FAILED_PRECONDITION mit einem Hinweis wie „location is not supported“.
• 403 PERMISSION_DENIED, möglicherweise im Zusammenhang mit Projekt, Abrechnung oder regionalen Rechten.

Zwei Begriffe werden oft verwechselt: Region der Kontoregistrierung und Region des Anfrageausgangs. Selbst wenn das Konto nutzbar ist, kann eine Anfrage abgelehnt werden, weil der Server in einer nicht unterstützten Region steht. Umgekehrt bedeutet ein lokaler Proxy, der Webseiten öffnet, nicht, dass API-Anfragen denselben Weg nehmen.

Empfohlene Reihenfolge:

1. Klären, ob die Anfrage vom lokalen Rechner, aus einem Container oder von einem Server kommt, und die tatsächliche Ausgangs-IP ermitteln.
2. Prüfen, ob die Ausgangsregion in der offiziellen Unterstützungsliste steht.
3. Die Region der Cloud-Instanz kontrollieren und bei Bedarf in eine unterstützte Region wechseln.
4. Wenn das Geschäft überwiegend in China liegt, eine Anbindung über ein konformes Gateway prüfen, das Netz und Abrechnung bündelt.
5. „IP wechseln“ nicht als einzige Lösung betrachten; zuerst Nutzungsbedingungen und lokale Vorschriften klären.

6. Weitere häufige Fehler

Symptom	Häufige Ursache	Behandlung
400 INVALID_ARGUMENT	Fehlerhafte JSON-Struktur, falsche Rollenreihenfolge, nicht unterstütztes Bildformat	Minimale Anfrage schrittweise erweitern
400 FAILED_PRECONDITION	Region nicht unterstützt, Abrechnung nicht aktiv, Vorbedingung fehlt	Region, Abrechnung und Projektstatus prüfen
403 PERMISSION_DENIED	API nicht aktiviert, Key-Einschränkung, fehlende Projektrechte	In der Konsole aktivieren und Rechte prüfen
500 INTERNAL	Interner Upstream-Fehler	Backoff, Request-ID speichern
503 UNAVAILABLE	Upstream überlastet oder Wartung	Backoff, Ausweichmodell
Antwort ohne Inhalt	Sicherheitsfilter, abgeschnittene Ausgabe	blockReason und finishReason prüfen
Ausgabe bricht ab	Maximale Ausgabe-Token erreicht	Limit erhöhen oder Eingabe kürzen

„Antwort vorhanden, aber ohne Inhalt“ wird oft als Störung gewertet, ist aber meist Sicherheitsfilter oder Längenbegrenzung. Zuerst promptFeedback.blockReason, finishReason und usageMetadata prüfen, dann entscheiden, ob der Prompt oder ein Parameter geändert wird.

7. Empfohlene Prüfreihenfolge

1. Vollständige Fehler-JSON, Anfragezeit, Modell-ID und Request-ID speichern.
2. Mit curl eine minimale Anfrage senden, um Client und SDK als Störquelle auszuschließen.
3. Drei Dinge abgleichen: Base URL, Authentifizierungsheader, Modell-ID.
4. Ein bekannt funktionierendes Modell testen, um Modell- und Kettenproblem zu trennen.
5. Kontingent, Abrechnung und Projektstatus prüfen, um 429 von 403 zu unterscheiden.
6. Ausgangsregion und Netzpfad der Anfrage bestätigen.
7. Zuletzt Client-Konfiguration, Proxy-Einstellungen und Retry-Logik im Code prüfen.

Immer nur eine Variable gleichzeitig ändern. Sonst lässt sich auch nach der Behebung nicht sagen, welcher Schritt geholfen hat, und der nächste Vorfall wiederholt sich.

8. Häufige Fragen

Worin unterscheiden sich 401 und 403?

401 bedeutet „Identität nicht bestätigt“; vorrangig Key, Authentifizierungsheader und Adresszuordnung prüfen. 403 bedeutet „Identität bestätigt, aber keine Berechtigung“; vorrangig API-Aktivierung, Projektrechte, Key-Einschränkungen und Regionspolitik prüfen.

Reicht es bei 429, einige Minuten zu warten?

Das hängt vom Kontingenttyp ab. Minutenbegrenzungen erholen sich nach Backoff meist; ein erschöpftes Tageskontingent erfordert Reset oder Erhöhung. Zuerst Kontingent-ID und Empfehlung im Fehlerkörper lesen, nicht blind erneut senden.

Löst eine andere IP das Regionsproblem?

Nicht unbedingt. Entscheidend sind tatsächliche Ausgangsregion, Kontostatus und Nutzungsbedingungen. Für Unternehmen ist die Bereitstellung in einer unterstützten Region oder die Anbindung über ein konformes Gateway stabiler.

Offizielle Adresse funktioniert, Gateway liefert 404 – wessen Problem?

Zuerst Base URL und Modell-ID des Gateways prüfen. Modellbenennung, Pfade und verfügbarer Umfang können vom offiziellen Angebot abweichen; offizielle Anfragen lassen sich nicht unverändert übernehmen. Das minimale Beispiel aus der Gateway-Dokumentation schrittweise einsetzen.

Wie verhindert man, dass Wiederholungen die Kosten vervielfachen?

Maximale Wiederholungszahl, exponentielles Backoff und Timeouts setzen; 429 separat behandeln; nicht-idempotente Anfragen deduplizieren; gatewayseitig Budgetgrenzen und Alarme einrichten.

Nächster Schritt

Der Schlüssel zur Gemini-Fehlerdiagnose liegt darin, zuerst die vier Gruppen Authentifizierung, Pfad, Kontingent und Netz zu trennen und dann mit minimalen Anfragen einzeln zu prüfen. Wer einen einheitlichen Einstieg und weniger Unsicherheit bei der Direktverbindung aus China benötigt, kann sich im ZSQH AI Gateway registrieren; Modelle, Kontingente und Preise stehen auf der Seite Modellpreise.

Weiterlesen:

• Gemini API in China: Zugang, Kontingente und Alternativen
• Gemini API einrichten: Key, Endpunkt und erster Aufruf
• Modellpreise und Abrechnung