In diesem Leitfaden finden Sie Informationen zur Diagnose und Behebung häufiger Probleme, die beim Aufrufen der Gemini API auftreten können. Es können Probleme mit dem Gemini API-Backend-Dienst oder den Client-SDKs auftreten. Unsere Client-SDKs sind in den folgenden Repositories als Open Source verfügbar:
Wenn Probleme mit dem API-Schlüssel auftreten, prüfen Sie, ob Sie den API-Schlüssel gemäß der Anleitung zur Einrichtung des API-Schlüssels richtig eingerichtet haben.
Fehlercodes
Eine vollständige Referenz aller Fehlercodes, einschließlich HTTP-Statuscodes, Codes für blockierte Generierung und Inhaltsfehlercodes, finden Sie auf der Seite API-Fehler.
Wiederholungsstrategie
Wenn Sie einen Fehler erhalten, der darauf hinweist, dass Sie Ihre Anfrage wiederholen sollten (z. B. 429 RESOURCE_EXHAUSTED oder 503 UNAVAILABLE), empfehlen wir, eine exponentielle Backoff-Strategie zu implementieren. Das bedeutet, dass Sie vor dem ersten Wiederholungsversuch kurz warten und die Wartezeit zwischen den nachfolgenden Wiederholungsversuchen dann schrittweise erhöhen.
Die offiziellen Client-SDKs für die Gemini API, z. B. das Python SDK, enthalten standardmäßig eine automatische Wiederholungslogik mit exponentiellem Backoff, um vorübergehende Fehler wie Zeitüberschreitungen, Netzwerkprobleme und Ratenbegrenzungen (Statuscodes 429 und 5xx) zu verarbeiten. Das Python SDK versucht beispielsweise automatisch, vorübergehende Fehler bis zu viermal mit einer anfänglichen Verzögerung von etwa 1 Sekunde und einer maximalen Verzögerung von 60 Sekunden zu wiederholen.
Wenn Sie direkte REST API-Anfragen stellen oder Ihre Wiederholungslogik anpassen, sollten Sie diese Best Practices befolgen, um die Wahrscheinlichkeit einer erfolgreichen Anfrage zu erhöhen und eine Überlastung des Dienstes zu vermeiden:
- Exponentiellen Backoff verwenden:Warten Sie vor dem ersten Wiederholungsversuch kurz (z. B. 1 Sekunde) und erhöhen Sie die Verzögerung dann exponentiell (z. B. 2 Sekunden, 4 Sekunden, 8 Sekunden).
- Jitter hinzufügen:Fügen Sie der Verzögerung einen zufälligen „Jitter“ hinzu, damit nicht alle Clients gleichzeitig einen neuen Versuch starten.
- Wiederholung bei bestimmten Fehlern:Wiederholen Sie den Vorgang nur bei vorübergehenden Fehlern (z. B.
429,408oder5xx). Wiederholen Sie den Vorgang nicht bei Clientfehlern (z. B.400,402oder403), da diese auf Probleme wie ungültige API-Schlüssel, aufgebrauchtes Prepaid-Guthaben oder fehlerhafte Syntax hinweisen. - Maximale Anzahl von Wiederholungsversuchen festlegen:Legen Sie eine maximale Anzahl von Wiederholungsversuchen fest, um Endlosschleifen zu vermeiden.
API-Aufrufe auf Modellparameterfehler prüfen
Prüfen Sie, ob Ihre Modellparameter innerhalb der folgenden Werte liegen:
| Modellparameter | Werte (Bereich) |
| Anzahl der Kandidaten | 1–8 (Ganzzahl) |
| Temperatur | 0,0–1,0 |
| Maximale Ausgabetokens | Auf der Seite „Modelle“ können Sie die maximale Anzahl von Tokens für das von Ihnen verwendete Modell ermitteln. |
| TopP | 0,0–1,0 |
Prüfen Sie nicht nur die Parameterwerte, sondern auch, ob Sie die richtige API-Version (z.B. /v1 oder /v1beta) und das richtige Modell verwenden, das die von Ihnen benötigten Funktionen unterstützt. Wenn sich ein Feature beispielsweise in der Betaphase befindet, ist es nur in der API-Version /v1beta verfügbar.
Prüfen, ob du das richtige Modell hast
Prüfen Sie, ob Sie ein unterstütztes Modell verwenden, das auf unserer Modellseite aufgeführt ist.
Höhere Latenz oder Tokennutzung bei Thinking-Modellen
Eine höhere Latenz oder Tokennutzung tritt häufig auf, weil bei Gemini 3.x-Modellen das Nachdenken standardmäßig aktiviert ist. Eingestellte Gemini 2.5-Modelle verwenden ebenfalls standardmäßig Thinking.
Thinking-Modelle generieren interne Reasoning-Tokens, um die Qualität zu verbessern. Dieser Reasoning-Prozess erhöht sowohl die Antwortlatenz als auch den Gesamttokenverbrauch.
Wenn Sie eine geringere Latenz bevorzugen oder die Kosten minimieren möchten, können Sie die Denkstufe senken oder das Denken deaktivieren.
Konfigurationsdetails und Codebeispiele finden Sie im Leitfaden zum Nachdenken.
Sicherheitsprobleme
Wenn Sie sehen, dass ein Prompt aufgrund einer Sicherheitseinstellung in Ihrem API-Aufruf blockiert wurde, prüfen Sie den Prompt im Hinblick auf die Filter, die Sie im API-Aufruf festgelegt haben.
Wenn Sie BlockedReason.OTHER sehen, verstößt die Anfrage oder Antwort möglicherweise gegen die Nutzungsbedingungen oder wird anderweitig nicht unterstützt.
Problem mit der Wiedergabe
Wenn das Modell die Ausgabe aufgrund des RECITATION-Grunds nicht mehr generiert, bedeutet dies, dass die Modellausgabe bestimmten Daten ähneln kann. Versuchen Sie, den Prompt bzw. Kontext so eindeutig wie möglich zu gestalten und eine höhere Temperatur zu verwenden.
Problem mit sich wiederholenden Tokens
Wenn Sie wiederholte Ausgabetokens sehen, versuchen Sie es mit den folgenden Vorschlägen, um sie zu reduzieren oder zu eliminieren.
| Beschreibung | Ursache | Vorgeschlagener Workaround |
|---|---|---|
| Wiederholte Bindestriche in Markdown-Tabellen | Dies kann passieren, wenn der Inhalt der Tabelle lang ist, da das Modell versucht, eine visuell ausgerichtete Markdown-Tabelle zu erstellen. Die Ausrichtung in Markdown ist jedoch für das korrekte Rendering nicht erforderlich. |
Fügen Sie Ihrem Prompt Anweisungen hinzu, um dem Modell spezifische Richtlinien für die Generierung von Markdown-Tabellen zu geben. Geben Sie Beispiele an, die diesen Richtlinien entsprechen. Du kannst auch versuchen, die Temperatur anzupassen. Für die Generierung von Code oder sehr strukturierten Ausgaben wie Markdown-Tabellen haben sich hohe Temperaturen (>= 0,8) als besser erwiesen. Hier ist ein Beispiel für Richtlinien, die Sie Ihrem Prompt hinzufügen können, um dieses Problem zu vermeiden:
# Markdown Table Format
* Separator line: Markdown tables must include a separator line below
the header row. The separator line must use only 3 hyphens per
column, for example: |---|---|---|. Using more hypens like
----, -----, ------ can result in errors. Always
use |:---|, |---:|, or |---| in these separator strings.
For example:
| Date | Description | Attendees |
|---|---|---|
| 2024-10-26 | Annual Conference | 500 |
| 2025-01-15 | Q1 Planning Session | 25 |
* Alignment: Do not align columns. Always use |---|.
For three columns, use |---|---|---| as the separator line.
For four columns use |---|---|---|---| and so on.
* Conciseness: Keep cell content brief and to the point.
* Never pad column headers or other cells with lots of spaces to
match with width of other content. Only a single space on each side
is needed. For example, always do "| column name |" instead of
"| column name |". Extra spaces are wasteful.
A markdown renderer will automatically take care displaying
the content in a visually appealing form.
|
| Wiederholte Tokens in Markdown-Tabellen | Ähnlich wie bei den wiederholten Bindestrichen tritt dies auf, wenn das Modell versucht, den Inhalt der Tabelle visuell auszurichten. Die Ausrichtung in Markdown ist für das korrekte Rendering nicht erforderlich. |
|
Wiederholte Zeilenumbrüche (\n) in strukturierter Ausgabe
|
Wenn die Modelleingabe Unicode- oder Escape-Sequenzen wie \u oder \t enthält, kann dies zu wiederholten Zeilenumbrüchen führen.
|
|
| Wiederholter Text bei Verwendung der strukturierten Ausgabe | Wenn die Modellausgabe eine andere Reihenfolge für die Felder hat als das definierte strukturierte Schema, kann dies zu sich wiederholendem Text führen. |
|
| Wiederholte Toolaufrufe | Das kann passieren, wenn das Modell den Kontext früherer Gedanken verliert und/oder einen nicht verfügbaren Endpunkt aufruft, zu dem es gezwungen wird. |
Weisen Sie das Modell an, den Status innerhalb seines Denkprozesses beizubehalten.
Fügen Sie am Ende Ihrer Systemanweisungen Folgendes hinzu:
When thinking silently: ALWAYS start the thought with a brief
(one sentence) recap of the current progress on the task. In
particular, consider whether the task is already done.
|
| Sich wiederholender Text, der nicht Teil der strukturierten Ausgabe ist | Das kann passieren, wenn das Modell bei einer Anfrage hängen bleibt, die es nicht auflösen kann. |
|
Projekt eingeschränkt oder nicht verfügbar
Wenn Ihre API-Anfragen 403 PERMISSION_DENIED („Der Zugriff auf Ihr Projekt wurde verweigert“) zurückgeben oder der Projektstatus in Google AI Studio Eingeschränkt, Kostenlose Stufe nicht verfügbar, Zahlung erforderlich oder Nicht verfügbar lautet, prüfen Sie, welcher der folgenden Abschnitte auf Ihr Projekt zutrifft:
Kostenlose Stufe der Gemini API nicht verfügbar
Nicht alle Google Cloud-Projekte oder ‑Konten sind für die kostenlose Stufe der Gemini API berechtigt. Wenn Ihr Projekt die kostenlose Stufe nicht nutzen darf:
- Das Erstellen eines neuen API-Schlüssels im selben Projekt behebt den Fehler nicht. Google prüft die Berechtigung auf Ebene des Google Cloud-Projekts.
- Wenn Sie die Gemini API mit diesem Projekt verwenden möchten, müssen Sie ein Upgrade auf die kostenpflichtige Stufe durchführen, indem Sie ein aktives Cloud-Rechnungskonto verknüpfen.
- Hinweis: Durch ein Upgrade eines Projekts auf die kostenpflichtige Stufe wird kein Kontingent der kostenlosen Stufe freigeschaltet. Google stellt die Nutzung der kostenpflichtigen Stufe gemäß den Gemini API-Preisen in Rechnung oder zieht sie von berechtigtem Google Cloud-Guthaben ab.
Zahlung für Cloud-Rechnungskonto erforderlich
Wenn Ihr Projekt bereits mit einem Cloud-Rechnungskonto verknüpft ist und Zahlung erforderlich angezeigt wird (oder 403 PERMISSION_DENIED mit Verweis auf einen ausstehenden Betrag zurückgegeben wird):
- Rufen Sie die Seite „Abrechnung“ in AI Studio oder die Google Cloud Billing Console auf, um überfällige Beträge zu begleichen oder Ihre Zahlungsmethode zu aktualisieren.
- Sobald Ihr Rechnungskonto wieder einwandfrei ist, erhält Ihr Projekt automatisch wieder API-Zugriff.
Geleakte oder blockierte API-Schlüssel
Wenn im Fehlerstatus 403 PERMISSION_DENIED angegeben ist, dass Ihr API-Schlüssel als geleakt oder blockiert gemeldet wurde:
- Rufen Sie die Seite „AI Studio-API-Schlüssel“ auf, um einen neuen API-Schlüssel zu generieren und die Anmeldedaten für Ihre Anwendung zu aktualisieren.
- Betten Sie API-Schlüssel niemals direkt in clientseitigen Code oder öffentliche Repositories ein.
Sperrung von Projekten oder Rechnungskonten aufgrund von Richtlinienverstößen
Wenn Google Ihr Google Cloud-Projekt oder Cloud-Rechnungskonto aufgrund eines Richtlinienverstoßes sperrt, prüfen Sie die zugehörige E-Mail-Adresse. Rufen Sie die Google Cloud Console auf, um Sperrungsbenachrichtigungen zu prüfen, und folgen Sie den Richtlinien für die Projektsperrung.
Blockierte oder nicht funktionierende API-Schlüssel
In diesem Abschnitt wird beschrieben, wie Sie prüfen, ob Ihr Gemini API-Schlüssel blockiert ist, und was Sie in diesem Fall tun können.
Gründe für die Sperrung von Schlüsseln
Wir haben eine Sicherheitslücke festgestellt, durch die einige API-Schlüssel möglicherweise öffentlich zugänglich waren. Um Ihre Daten zu schützen und unbefugten Zugriff zu verhindern, haben wir proaktiv den Zugriff auf die Gemini API mit diesen bekannten geleakten Schlüsseln blockiert.
Prüfen, ob Ihre Schlüssel betroffen sind
Wenn bekannt ist, dass Ihr Schlüssel geleakt wurde, können Sie ihn nicht mehr mit der Gemini API verwenden. In Google AI Studio können Sie prüfen, ob einer Ihrer API-Schlüssel für den Aufruf der Gemini API blockiert ist, und neue Schlüssel generieren. Möglicherweise wird auch der folgende Fehler zurückgegeben, wenn Sie versuchen, diese Schlüssel zu verwenden:
Your API key was reported as leaked. Please use another API key.
Aktion für blockierte API-Schlüssel
Sie sollten mit Google AI Studio neue API-Schlüssel für Ihre Gemini API-Integrationen generieren. Wir empfehlen dringend, Ihre API-Schlüsselverwaltung zu überprüfen, um sicherzustellen, dass Ihre neuen Schlüssel sicher aufbewahrt und nicht öffentlich zugänglich sind.
Unerwartete Kosten aufgrund von Sicherheitslücken
Supportanfrage zur Abrechnung einreichen Unser Abrechnungsteam arbeitet daran und wir werden Sie so schnell wie möglich über Neuigkeiten informieren.
Sicherheitsmaßnahmen von Google für geleakte Schlüssel
Wie schützt Google mein Konto vor Kostenüberschreitungen und Missbrauch, wenn meine API-Schlüssel preisgegeben werden?
- Wir stellen die Ausgabe von API-Schlüsseln um. Wenn Sie einen neuen Schlüssel über Google AI Studio anfordern, ist dieser standardmäßig nur auf Google AI Studio beschränkt und akzeptiert keine Schlüssel von anderen Diensten. So wird eine unbeabsichtigte Verwendung von Schlüsseln verhindert.
- Wir blockieren standardmäßig API-Schlüssel, die geleakt und mit der Gemini API verwendet werden, um Missbrauch von Kosten und Ihren Anwendungsdaten zu verhindern.
- Den Status Ihrer API-Schlüssel finden Sie in Google AI Studio. Wir arbeiten daran, Sie proaktiv zu informieren, wenn wir feststellen, dass Ihre API-Schlüssel geleakt wurden, damit Sie sofort Maßnahmen ergreifen können.
Modellausgabe verbessern
Wenn Sie die Qualität der Modellausgaben verbessern möchten, sollten Sie strukturiertere Prompts schreiben. Auf der Seite Leitfaden für Prompt Engineering werden einige grundlegende Konzepte, Strategien und Best Practices vorgestellt, die Ihnen den Einstieg erleichtern.
Informationen zu Tokenlimits
In unserem Leitfaden zu Tokens erfahren Sie, wie Tokens gezählt werden und welche Limits gelten.
Bekannte Probleme
- Die API unterstützt nur eine begrenzte Anzahl von Sprachen. Wenn Sie Prompts in nicht unterstützten Sprachen senden, kann dies zu unerwarteten oder sogar blockierten Antworten führen. Aktuelle Informationen zu den verfügbaren Sprachen findest du hier.
Fehler melden
Wenn Sie Fragen haben, können Sie sich im Google AI-Entwicklerforum an der Diskussion beteiligen.