In diesem Leitfaden erfahren Sie, wie Sie häufige Probleme diagnostizieren und beheben, die beim Aufrufen der Gemini API auftreten. Probleme können entweder im Backend-Dienst der Gemini API oder in den Client-SDKs auftreten. Unsere Client-SDKs sind Open Source und in den folgenden Repositorys verfügbar:
Wenn Probleme mit dem API-Schlüssel auftreten, prüfen Sie, ob Sie Ihren 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 Fehlercodes für Inhalte, finden Sie auf der API-Fehler Seite.
Wiederholungsstrategie
Wenn Sie eine Fehlermeldung erhalten, die darauf hinweist, dass Sie die 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 eine kurze Zeit warten und dann die Wartezeit zwischen den nachfolgenden Wiederholungsversuchen allmählich verlängern.
Die offiziellen Client-SDKs für die Gemini API, z. B. das Python SDK, enthalten standardmäßig eine automatische Wiederholungslogik mit exponentiellem Backoff zur Behandlung vorübergehender Fehler wie Zeitüberschreitungen, Netzwerkprobleme und Ratenbegrenzungen (429 und 5xx Statuscodes). Das Python SDK wiederholt vorübergehende Fehler beispielsweise automatisch bis zu viermal mit einer anfänglichen Verzögerung von etwa 1 Sekunde und einer maximalen Verzögerung von 60 Sekunden.
Wenn Sie direkte REST API-Anfragen stellen oder Ihre Wiederholungslogik anpassen, folgen Sie diesen Best Practices, um die Wahrscheinlichkeit einer erfolgreichen Anfrage zu erhöhen und den Dienst nicht zu überlasten:
- Exponentiellen Backoff verwenden:Warten Sie vor dem ersten Wiederholungsversuch eine kurze Zeit (z. B. 1 Sekunde) und verlängern Sie dann die Verzögerung exponentiell (z. B. 2, 4, 8 Sekunden).
- Jitter hinzufügen:Fügen Sie der Verzögerung zufälligen „Jitter“ hinzu, um zu verhindern, dass alle Clients genau gleichzeitig einen Wiederholungsversuch starten.
- Wiederholungsversuche bei bestimmten Fehlern:Wiederholen Sie nur vorübergehende Fehler (z. B.
429,408oder5xx). Wiederholen Sie keine Clientfehler (z. B.400,402oder403), da diese auf Probleme wie ungültige API-Schlüssel, aufgebrauchte Guthaben oder fehlerhafte Syntax hinweisen. - Maximale Anzahl an Wiederholungsversuchen festlegen:Definieren Sie eine maximale Anzahl an Wiederholungsversuchen, um Endlosschleifen zu vermeiden.
API-Aufrufe auf Fehler bei Modellparametern prüfen
Prüfen Sie, ob die 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 an Tokens für das 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 benötigten Funktionen unterstützt. Wenn sich eine Funktion beispielsweise in der Betaphase befindet, ist sie nur in der API-Version /v1beta verfügbar.
Prüfen, ob das richtige Modell verwendet wird
Prüfen Sie, ob Sie ein unterstütztes Modell verwenden, das auf unserer Seite Modelle aufgeführt ist.
Höhere Latenz oder Tokennutzung bei Modellen mit Denkprozess
Eine höhere Latenz oder Tokennutzung tritt häufig auf, weil bei Gemini 3.x-Modellen standardmäßig der Denkprozess aktiviert ist. Auch bei den eingestellten Gemini 2.5-Modellen wird standardmäßig der Denkprozess verwendet.
Modelle mit Denkprozess generieren interne Tokens für den Denkprozess, um die Qualität zu verbessern. Dieser Denkprozess erhöht sowohl die Antwortlatenz als auch den gesamten Tokenverbrauch.
Wenn Sie eine geringere Latenz bevorzugen oder Kosten minimieren müssen, können Sie den Denkprozess reduzieren oder deaktivieren.
Details zur Konfiguration und Codebeispiele finden Sie im Leitfaden zum Denkprozess.
Sicherheitsprobleme
Wenn 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 BlockedReason.OTHER angezeigt wird, 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 Grunds RECITATION beendet, ähnelt die Modellausgabe möglicherweise bestimmten Daten. Um dieses Problem zu beheben, versuchen Sie, den Prompt / Kontext so eindeutig wie möglich zu gestalten und eine höhere Temperatur zu verwenden.
Problem mit wiederholten Tokens
Wenn wiederholte Ausgabetokens angezeigt werden, versuchen Sie es mit den folgenden Vorschlägen, um sie zu reduzieren oder zu entfernen.
| Beschreibung | Ursache | Vorgeschlagene Problemumgehung |
|---|---|---|
| Wiederholte Bindestriche in Markdown-Tabellen | Dies kann auftreten, wenn die Inhalte der Tabelle lang sind, 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. Sie können auch versuchen, die Temperatur anzupassen. Für die Generierung Code oder sehr strukturierter Ausgabe wie Markdown-Tabellen, haben sich hohe Temperaturen (>= 0,8) als besser erwiesen. Im Folgenden finden Sie 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, die Inhalte 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, kann dies zu wiederholten Zeilenumbrüchen führen.
|
|
| Wiederholter Text bei Verwendung strukturierter Ausgabe | Wenn die Reihenfolge der Felder in der Modellausgabe von der Reihenfolge im definierten strukturierten Schema abweicht, kann dies zu wiederholtem Text führen. |
|
| Wiederholte Toolaufrufe | Dies kann auftreten, wenn das Modell den Kontext früherer Gedanken verliert und/oder einen nicht verfügbaren Endpunkt aufruft, zu dem es gezwungen ist. |
Weisen Sie das Modell an, den Status im Denkprozess beizubehalten.
Fügen Sie dies am Ende Ihrer Systemanweisungen 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.
|
| Wiederholter Text, der nicht Teil der strukturierten Ausgabe ist | Dies kann auftreten, wenn das Modell bei einer Anfrage hängen bleibt, die es nicht lösen kann. |
|
Blockierte oder nicht funktionierende API-Schlüssel
In diesem Abschnitt wird beschrieben, wie Sie prüfen können, ob Ihr Gemini API-Schlüssel blockiert ist, und was Sie dagegen tun können.
Gründe für die Blockierung von Schlüsseln
Wir haben eine Sicherheitslücke festgestellt, durch die einige API-Schlüssel öffentlich zugänglich geworden sein könnten. Um Ihre Daten zu schützen und unbefugten Zugriff zu verhindern, haben wir diese bekannten kompromittierten Schlüssel proaktiv für den Zugriff auf die Gemini API blockiert.
Prüfen, ob Ihre Schlüssel betroffen sind
Wenn Ihr Schlüssel kompromittiert 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.
Maßnahmen für blockierte API-Schlüssel
Generieren Sie in Google AI Studio neue API-Schlüssel für Ihre Gemini API-Integrationen. Wir empfehlen dringend, Ihre API-Schlüsselverwaltungspraktiken zu überprüfen, um sicherzustellen, dass Ihre neuen Schlüssel sicher aufbewahrt werden und nicht öffentlich zugänglich sind.
Unerwartete Kosten aufgrund einer Sicherheitslücke
Reichen Sie eine Supportanfrage zur Abrechnung ein. Unser Abrechnungsteam arbeitet an diesem Problem und wir werden Sie so schnell wie möglich über Neuigkeiten informieren.
Sicherheitsmaßnahmen von Google für kompromittierte Schlüssel
Wie schützt Google mein Konto vor Kostenüberschreitungen und Missbrauch, wenn meine API-Schlüssel kompromittiert wurden?
- Wir werden API-Schlüssel ausgeben, wenn Sie in Google AI Studio einen neuen Schlüssel anfordern. Diese Schlüssel sind standardmäßig nur für Google AI Studio gültig und akzeptieren keine Schlüssel von anderen Diensten. So wird eine unbeabsichtigte Verwendung von Schlüsseln verhindert.
- Wir blockieren standardmäßig API-Schlüssel, die kompromittiert wurden und mit der Gemini API verwendet werden, um Missbrauch von Kosten und Ihren Anwendungsdaten zu verhindern.
- In Google AI Studio können Sie den Status Ihrer API-Schlüssel einsehen. Wir werden Sie proaktiv informieren, wenn wir feststellen, dass Ihre API-Schlüssel kompromittiert wurden, damit Sie sofort Maßnahmen ergreifen können.
Modellausgabe verbessern
Wenn Sie Modellausgaben von höherer Qualität wünschen, 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 mehr darüber, wie Sie Tokens zählen und welche Limits gelten.
Bekannte Probleme
- Die API unterstützt nur eine begrenzte Anzahl ausgewählter Sprachen. Wenn Sie Prompts in nicht unterstützten Sprachen einreichen, können unerwartete oder sogar blockierte Antworten zurückgegeben werden. Auf der Seite Verfügbare Sprachen finden Sie aktuelle Informationen.
Fehler melden
Wenn Sie Fragen haben, können Sie sich im Google AI-Entwicklerforum austauschen.