In diesem Leitfaden finden Sie Informationen zur Diagnose und Behebung häufiger Probleme, die beim Aufrufen der Gemini API auftreten können. 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 Repositories verfügbar:
Wenn Sie Probleme mit dem API-Schlüssel haben, prüfen Sie, ob Sie ihn gemäß der Anleitung zum Einrichten von API-Schlüsseln 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 Strategie für exponentiellen Backoff zu implementieren. Das bedeutet, dass Sie vor dem ersten Wiederholungsversuch eine kurze Zeit warten und dann die Wartezeit zwischen den nachfolgenden Wiederholungsversuchen allmählich 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 zur Verarbeitung vorübergehender Fehler wie Zeitüberschreitungen, Netzwerkprobleme und Ratenbeschränkungen (Statuscodes 429 und 5xx). Das Python SDK wiederholt beispielsweise vorübergehende Fehler 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, sollten Sie diese Best Practices befolgen, um die Wahrscheinlichkeit einer erfolgreichen Anfrage zu erhöhen und den Dienst nicht zu überlasten:
- Exponentielles Backoff verwenden:Warten Sie vor dem ersten Wiederholungsversuch eine kurze Zeit (z. B. 1 Sekunde) und verlängern Sie die Verzögerung dann exponentiell (z. B. 2 Sekunden, 4 Sekunden, 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.
- Wiederholung bei bestimmten Fehlern: Wiederholen Sie nur vorübergehende Fehler wie
429,408oder5xx. Wiederholen Sie keine Clientfehler wie400,402oder403, da diese auf Probleme wie ungültige API-Schlüssel, aufgebrauchte Vorauszahlung-Guthaben oder falsche 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 Parameter Ihres Modells die folgenden Werte einhalten:
| 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 |
Achten Sie nicht nur auf die Parameterwerte, sondern auch darauf, dass 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 /v1beta-API-Version verfügbar.
Prüfen, ob Sie das richtige Modell haben
Prüfen Sie, ob Sie ein unterstütztes Modell verwenden, das auf unserer Seite „Modelle“ aufgeführt ist.
Höhere Latenz oder Tokennutzung bei Denkmodellen
Eine höhere Latenz oder Token-Nutzung tritt häufig auf, weil bei Gemini 3.x-Modellen standardmäßig die Funktion „Denken“ aktiviert ist. Bei eingestellten Gemini 2.5-Modellen wird ebenfalls die Standarddenkweise verwendet.
Denkmodelle generieren interne Begründungs-Tokens, um die Qualität zu verbessern. Dieser Prozess erhöht sowohl die Antwortlatenz als auch den Gesamtverbrauch an Tokens.
Wenn Sie eine geringere Latenz priorisieren oder die Kosten minimieren möchten, können Sie die Denkstufe senken oder das Denken deaktivieren.
Konfigurationsdetails und Codebeispiele finden Sie im Thinking Guide.
Sicherheitsprobleme
Wenn ein Prompt aufgrund einer Sicherheitseinstellung in Ihrem API-Aufruf blockiert wurde, überprü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 Rezitation
Wenn das Modell die Ausgabe aufgrund des Grunds RECITATION beendet, bedeutet das, dass die Modellausgabe bestimmten Daten ähneln kann. Um das Problem zu beheben, sollten Sie den Prompt bzw. Kontext so einzigartig wie möglich gestalten und eine höhere Temperatur verwenden.
Problem mit sich wiederholenden Tokens
Wenn Sie wiederholte Ausgabetokens sehen, können Sie versuchen, sie mit den folgenden Vorschlägen zu reduzieren oder zu eliminieren.
| Beschreibung | Ursache | Vorgeschlagene Problemumgehung |
|---|---|---|
| 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 Rendern 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 von Code oder sehr strukturierten Ausgaben wie Markdown-Tabellen hat sich eine hohe Temperatur (>= 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, den Inhalt der Tabelle visuell auszurichten. Die Ausrichtung in Markdown ist für das korrekte Rendern 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 strukturierter Ausgabe | Wenn die Felder in der Modellausgabe in einer anderen Reihenfolge als im definierten strukturierten Schema stehen, kann dies zu sich wiederholendem Text führen. |
|
| Wiederholte Toolaufrufe | Das kann passieren, wenn das Modell den Kontext früherer Überlegungen verliert und/oder einen nicht verfügbaren Endpunkt aufruft, zu dem es gezwungen wird. |
Weisen Sie das Modell an, den Status in seinem Denkprozess beizubehalten.
Fügen Sie Folgendes 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 | Das kann passieren, wenn das Modell bei einer Anfrage hängen bleibt, die es nicht beantworten kann. |
|
Blockierte oder nicht funktionierende API-Schlüssel
In diesem Abschnitt wird beschrieben, wie Sie prüfen, ob Ihr Gemini API-Schlüssel gesperrt ist, und was Sie in diesem Fall tun können.
Gründe für die Sperrung von Schlüsseln
Wir haben eine Sicherheitslücke entdeckt, durch die einige API-Schlüssel öffentlich zugänglich gemacht wurden. Zum Schutz Ihrer Daten und zur Verhinderung von unbefugtem Zugriff haben wir den Zugriff auf die Gemini API für diese bekannten geleakten Schlüssel proaktiv blockiert.
Prüfen, ob Ihre Schlüssel betroffen sind
Wenn Ihr Schlüssel offengelegt wurde, können Sie ihn nicht mehr mit der Gemini API verwenden. In Google AI Studio können Sie nachsehen, ob Ihre API-Schlüssel für Aufrufe der Gemini API gesperrt sind, 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 bei blockierten API-Schlüsseln
Sie sollten neue API-Schlüssel für Ihre Gemini API-Integrationen mit Google AI Studio 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 bald wie möglich über Neuigkeiten informieren.
Sicherheitsmaßnahmen von Google bei offengelegten Schlüsseln
Wie kann Google mein Konto vor Kostenüberschreitungen und Missbrauch schützen, wenn meine API-Schlüssel offengelegt werden?
- Wir stellen API-Schlüssel künftig nur noch aus, wenn Sie einen neuen Schlüssel über Google AI Studio anfordern. Diese Schlüssel sind standardmäßig auf Google AI Studio beschränkt 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 offengelegt und mit der Gemini API verwendet werden. So können wir Missbrauch von Kosten und Ihren Anwendungsdaten verhindern.
- Den Status Ihrer API-Schlüssel finden Sie in Google AI Studio. Wir werden Sie proaktiv informieren, wenn wir feststellen, dass Ihre API-Schlüssel offengelegt wurden, damit Sie sofort Maßnahmen ergreifen können.
Modellausgabe verbessern
Wenn Sie eine höhere Qualität der Modellausgaben wünschen, sollten Sie strukturiertere Prompts schreiben. Auf der Seite Leitfaden zum 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 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 einreichen, kann das zu unerwarteten oder sogar blockierten Antworten führen. Verfügbare Sprachen
Fehler melden
Wenn Sie Fragen haben, können Sie sich im Google AI-Entwicklerforum an der Diskussion beteiligen.