In diesem Leitfaden erfahren Sie, wie Sie häufige Probleme beim Aufrufen der Gemini API diagnostizieren und beheben. Es kann Probleme mit dem Gemini API-Back-End-Dienst oder den Client-SDKs geben. Unsere Client-SDKs sind in den folgenden Repositories als Open Source verfügbar:
Wenn Probleme mit API-Schlüsseln auftreten, prüfen Sie, ob Sie Ihren API-Schlüssel gemäß der Anleitung zur Einrichtung von API-Schlüsseln richtig eingerichtet haben.
Fehlercodes des Gemini API-Backend-Dienstes
In der folgenden Tabelle sind häufige Backend-Fehlercodes aufgeführt, die Sie möglicherweise sehen, zusammen mit Erklärungen zu den Ursachen und Schritten zur Fehlerbehebung:
| HTTP-Code | Status | Beschreibung | Beispiel | Lösung |
| 400 | INVALID_ARGUMENT | Der Anfragetext ist fehlerhaft. | In Ihrer Anfrage gibt es einen Tippfehler oder ein Pflichtfeld fehlt. | Informationen zum Anfrageformat, zu Beispielen und zu unterstützten Versionen finden Sie in der API-Referenz. Die Verwendung von Funktionen einer neueren API-Version mit einem älteren Endpunkt kann 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 die kostenlose Stufe nicht unterstützt wird, und Sie haben die Abrechnung für Ihr Projekt in Google AI Studio nicht aktiviert. | Wenn Sie die Gemini API verwenden möchten, müssen Sie in Google AI Studio einen kostenpflichtigen Tarif einrichten. |
| 403 | PERMISSION_DENIED | Ihr API-Schlüssel hat nicht die erforderlichen Berechtigungen. | Sie verwenden den falschen API-Schlüssel. Sie versuchen, ein optimiertes Modell zu verwenden, ohne eine ordnungsgemäße Authentifizierung durchzuführen. | Prüfen Sie, ob Ihr API-Schlüssel festgelegt ist und über den richtigen Zugriff verfügt. Außerdem müssen Sie sich authentifizieren, um optimierte Modelle verwenden zu können. |
| 404 | NOT_FOUND | Die angeforderte Ressource wurde nicht gefunden. | Eine Bild-, Audio- oder Videodatei, auf die in Ihrer Anfrage verwiesen wird, 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 die Ratenbegrenzung überschritten. | Sie senden mit der kostenlosen Gemini API zu viele Anfragen pro Minute. | Achten Sie darauf, dass Sie die Geschwindigkeitsbeschränkung des Modells einhalten. Fordern Sie bei Bedarf eine Kontingenterhöhung an. |
| 500 | INTERN | Auf der Seite von Google ist ein unerwarteter Fehler aufgetreten. | Der Eingabekontext ist zu lang. | Reduzieren Sie den Eingabekontext oder wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 1.5 Pro zu Gemini 1.5 Flash), um zu sehen, ob das Problem dadurch behoben wird. Sie können auch warten und die Anfrage dann noch einmal senden. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte über die Schaltfläche Feedback senden in Google AI Studio. |
| 503 | UNAVAILABLE | Möglicherweise ist der Dienst vorübergehend überlastet oder nicht erreichbar. | Die Kapazität des Dienstes ist vorübergehend erschöpft. | Wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 1.5 Pro zu Gemini 1.5 Flash) und prüfen Sie, ob das Problem dadurch behoben wird. Sie können auch warten und die Anfrage dann noch einmal senden. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte über die Schaltfläche Feedback senden in Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | Die Verarbeitung kann nicht innerhalb des Fristlimits abgeschlossen werden. | Ihr Prompt (oder Kontext) ist zu groß, um rechtzeitig verarbeitet zu werden. | Legen Sie in Ihrer Clientanfrage ein längeres Timeout fest, um diesen Fehler zu vermeiden. |
Client SDK-Fehlercodes
In der folgenden Tabelle sind häufig auftretende Fehlercodes des Python-Client-SDKs aufgeführt. Außerdem werden die zugehörigen Ursachen erläutert:
| Ausnahme-/Fehlertyp | Klasse | Beschreibung |
|---|---|---|
| APIError | google.genai.errors.APIError | Allgemeine Fehler, die von der GenAI API ausgelöst werden. |
| ClientError | google.genai.errors.ClientError | Von der GenAI API ausgelöster Clientfehler. |
| ServerError | google.genai.errors.ServerError | Von der GenAI API ausgelöster Serverfehler. |
| UnknownFunctionCallArgumentError | google.genai.errors.UnknownFunctionCallArgumentError | Wird ausgelöst, wenn das Argument des Funktionsaufrufs nicht in die Parameteranmerkung umgewandelt werden kann. |
| UnsupportedFunctionError | google.genai.errors.UnsupportedFunctionError | Wird ausgelöst, wenn die Funktion nicht unterstützt wird. |
| FunctionInvocationError | google.genai.errors.FunctionInvocationError | Wird ausgelöst, wenn die Funktion mit den angegebenen Argumenten nicht aufgerufen werden kann. |
| ValidationError | pydantic.ValidationError | Wird von Pydantic ausgelöst, wenn ein Fehler in den zu validierenden Daten gefunden wird. Weitere Informationen finden Sie unter Pydantic-Fehlerbehandlung. |
Alle Fehler finden Sie auch in der Klasse „errors“.
Zur Behandlung von vom SDK ausgelösten Fehlern kannst du einen try-except-Block verwenden:
from google.genai import errors
try:
client.models.generate_content(
model="invalid-model-name",
contents="What is your name?",
)
except errors.APIError as e:
print(e.code) # 404
print(e.message)
API-Aufrufe auf Fehler bei Modellparametern prüfen
Die Modellparameter müssen folgende Werte einhalten:
| Modellparameter | Werte (Bereich) |
| Anzahl der Kandidaten | 1–8 (Ganzzahl) |
| Temperatur | 0,0–1,0 |
| Max. Ausgabetokens |
Verwenden Sie get_model (Python), um die maximale Anzahl von Tokens für das verwendete Modell zu ermitteln.
|
| TopP | 0,0–1,0 |
Prüfe nicht nur die Parameterwerte, sondern auch, ob du die richtige API-Version verwendest (z.B. /v1 oder /v1beta) und ein Modell, 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
Achten Sie darauf, dass Sie ein unterstütztes Modell verwenden, das auf unserer Seite „Modelle“ aufgeführt ist.
Sicherheitsprobleme
Wenn eine Aufforderung aufgrund einer Sicherheitseinstellung in Ihrem API-Aufruf blockiert wurde, prüfen Sie die Aufforderung 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 beim Vorlesen
Wenn das Modell aufgrund des Grundes „REZITATION“ keine Ausgabe mehr generiert, bedeutet das, dass die Modellausgabe bestimmten Daten ähneln könnte. Versuchen Sie, den Prompt / Kontext so einzigartig wie möglich zu gestalten und verwenden Sie eine höhere Temperatur.
Modellausgabe verbessern
Für eine bessere Qualität der Modellausgaben sollten Sie strukturiertere Prompts verfassen. Auf der Seite Einführung in das Prompt-Design werden einige grundlegende Konzepte, Strategien und Best Practices vorgestellt, die Ihnen den Einstieg erleichtern.
Wenn Sie Hunderte von Beispielen für gute Eingabe/Ausgabe-Paare haben, können Sie auch die Modelloptimierung in Betracht ziehen.
Informationen zu Tokenlimits
In unserem Token-Leitfaden erfährst du mehr darüber, wie Tokens gezählt werden und welche Limits gelten.
Bekannte Probleme
- Die API unterstützt nur eine Reihe ausgewählter Sprachen. Wenn Sie Prompts in nicht unterstützten Sprachen einreichen, kann das zu unerwarteten oder sogar blockierten Antworten führen. Aktuelle Informationen zu den verfügbaren Sprachen findest du hier.
Fehler melden
Wenn Sie Fragen haben, nehmen Sie an der Diskussion im Google AI-Entwicklerforum teil.