Z tego przewodnika dowiesz się, jak diagnozować i rozwiązywać typowe problemy, które mogą wystąpić podczas wywoływania Gemini API. Problemy mogą występować zarówno w usłudze backendowej Gemini API, jak i w pakietach SDK klienta. Nasze pakiety SDK klienta są dostępne na licencji open source w tych repozytoriach:
Jeśli masz problemy z kluczem interfejsu API, sprawdź, czy został on prawidłowo skonfigurowany zgodnie z przewodnikiem konfiguracji klucza interfejsu API.
Kody błędów usługi backendowej Gemini API
W tabeli poniżej znajdziesz listę typowych kodów błędów backendu, które mogą wystąpić, wraz z wyjaśnieniami ich przyczyn i sposobami rozwiązywania problemów:
| Kod HTTP | Stan | Opis | Przykład | Rozwiązanie |
| 400 | INVALID_ARGUMENT | Treść żądania jest nieprawidłowa. | W żądaniu występuje literówka lub brakuje wymaganego pola. | Sprawdź dokumentację interfejsu API, aby dowiedzieć się więcej o formacie żądania, przykładach i obsługiwanych wersjach. Używanie funkcji z nowszej wersji interfejsu API ze starszym punktem końcowym może powodować błędy. |
| 400 | FAILED_PRECONDITION | Bezpłatna wersja Gemini API nie jest dostępna w Twoim kraju. Włącz rozliczenia w projekcie w Google AI Studio. | Wysyłasz żądanie w regionie, w którym poziom bezpłatny nie jest obsługiwany, i nie masz włączonych rozliczeń w projekcie w Google AI Studio. | Aby korzystać z Gemini API, musisz skonfigurować płatny plan w Google AI Studio. |
| 403 | PERMISSION_DENIED | Twój klucz interfejsu API nie ma wymaganych uprawnień. | Używasz nieprawidłowego klucza interfejsu API; używasz dostrojonego modelu bez odpowiedniego uwierzytelnienia. | Sprawdź, czy klucz interfejsu API jest ustawiony i ma odpowiedni dostęp. Upewnij się też, że masz odpowiednie uwierzytelnienie, aby używać dostrojonych modeli. |
| 404 | NOT_FOUND | Nie znaleziono żądanego zasobu. | Nie znaleziono pliku obrazu, dźwięku ani wideo, do którego odwołujesz się w żądaniu. | Sprawdź, czy wszystkie parametry w żądaniu są prawidłowe w przypadku Twojej wersji interfejsu API. |
| 429 | RESOURCE_EXHAUSTED | Przekroczono limit liczby żądań. | Wysyłasz zbyt wiele żądań na minutę za pomocą bezpłatnej wersji Gemini API. | Sprawdź, czy nie przekraczasz limitu liczby żądań modelu. W razie potrzeby poproś o zwiększenie limitu. |
| 499 | CANCELLED | Operacja została anulowana, zwykle przez element wywołujący. | Klient zamknął połączenie, zanim interfejs API zdążył odpowiedzieć. | Sprawdź, czy infrastruktura klienta lub sieci nie zamyka przedwcześnie połączenia (np. z powodu przekroczenia limitu czasu po stronie klienta). |
| 500 | WEWNĘTRZNY | Wystąpił nieoczekiwany błąd po stronie Google. | Kontekst wejściowy jest zbyt długi. | Sprawdź stronę stanu Gemini API, aby dowiedzieć się, czy występują jakieś problemy. Zmniejsz kontekst wejściowy lub tymczasowo przełącz się na inny model (np. z Gemini 2.5 Pro na Gemini 2.5 Flash) i sprawdź, czy to działa. Możesz też poczekać chwilę i ponowić żądanie. Jeśli problem będzie się powtarzał po ponowieniu próby, zgłoś go za pomocą przycisku Prześlij opinię w Google AI Studio. |
| 503 | PRODUKT NIEDOSTĘPNY | Usługa może być tymczasowo przeciążona lub niedostępna. | Usługa tymczasowo wyczerpuje zasoby. | Sprawdź stronę stanu Gemini API, aby dowiedzieć się, czy występują jakieś problemy. Tymczasowo przełącz się na inny model (np. z Gemini 2.5 Pro na Gemini 2.5 Flash) i sprawdź, czy to działa. Możesz też poczekać chwilę i ponowić żądanie. Jeśli problem będzie się powtarzał po ponowieniu próby, zgłoś go za pomocą przycisku Prześlij opinię w Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | Usługa nie może zakończyć przetwarzania w wyznaczonym terminie. | Prompt (lub kontekst) jest zbyt duży, aby można go było przetworzyć na czas. | Aby uniknąć tego błędu, ustaw dłuższy „limit czasu” w żądaniu klienta. |
Sprawdzanie wywołań interfejsu API pod kątem błędów parametrów modelu
Sprawdź, czy parametry modelu mieszczą się w tych wartościach:
| Parametr modelu | Wartości (zakres) |
| Liczba kandydatów | 1–8 (liczba całkowita) |
| Temperatura | 0,0–1,0 |
| Maksymalna liczba tokenów | Aby określić maksymalną liczbę tokenów dla używanego modelu, otwórz stronę modeli. |
| TopP | 0,0–1,0 |
Oprócz sprawdzania wartości parametrów upewnij się, że używasz prawidłowej
wersji interfejsu API (np. /v1 lub /v1beta) i
modelu, który obsługuje potrzebne Ci funkcje. Jeśli na przykład funkcja jest w wersji beta, będzie dostępna tylko w wersji interfejsu API /v1beta.
Sprawdzanie, czy masz odpowiedni model
Sprawdź, czy używasz obsługiwanego modelu wymienionego na naszej stronie modeli.
Większe opóźnienie lub wykorzystanie tokenów w przypadku modeli 2.5
Jeśli zauważysz większe opóźnienie lub wykorzystanie tokenów w przypadku modeli 2.5 Flash i Pro, może to być spowodowane tym, że myślenie jest domyślnie włączone w celu poprawy jakości. Jeśli priorytetem jest dla Ciebie szybkość lub chcesz zminimalizować koszty, możesz dostosować lub wyłączyć myślenie.
Wskazówki i przykładowy kod znajdziesz na stronie myślenia.
Problemy z bezpieczeństwem
Jeśli widzisz, że prompt został zablokowany z powodu ustawienia bezpieczeństwa w wywołaniu interfejsu API, sprawdź prompt pod kątem filtrów ustawionych w wywołaniu interfejsu API.
Jeśli widzisz BlockedReason.OTHER, zapytanie lub odpowiedź mogą naruszać warunki
korzystania z usługi lub być w inny sposób nieobsługiwane.
Problem z recytacją
Jeśli widzisz, że model przestaje generować dane wyjściowe z powodu RECITATION, oznacza to, że dane wyjściowe modelu mogą przypominać określone dane. Aby to naprawić, spróbuj, aby prompt lub kontekst były jak najbardziej unikalne, i użyj wyższej temperatury.
Problem z powtarzającymi się tokenami
Jeśli widzisz powtarzające się tokeny wyjściowe, spróbuj zastosować te sugestie, aby je ograniczyć lub wyeliminować.
| Opis | Przyczyna | Sugerowane obejście |
|---|---|---|
| Powtarzające się łączniki w tabelach Markdown | Może się to zdarzyć, gdy zawartość tabeli jest długa, ponieważ model próbuje utworzyć wizualnie wyrównaną tabelę Markdown. Wyrównanie w Markdown nie jest jednak konieczne do prawidłowego renderowania. |
Dodaj do prompta instrukcje, aby podać modelowi konkretne wytyczne dla generowania tabel Markdown. Podaj przykłady zgodne z tymi wytycznymi. Możesz też spróbować dostosować temperaturę. W przypadku generowania kodu lub bardzo ustrukturyzowanych danych wyjściowych, takich jak tabele Markdown, lepiej sprawdzają się wysokie temperatury (>= 0,8). Oto przykładowy zestaw wytycznych, które możesz dodać do swojego prompta, aby zapobiec temu problemowi:
# 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.
|
| Powtarzające się tokeny w tabelach Markdown | Podobnie jak w przypadku powtarzających się łączników, dzieje się tak, gdy model próbuje wizualnie wyrównać zawartość tabeli. Wyrównanie w Markdown nie jest nie jest wymagane do prawidłowego renderowania. |
|
Powtarzające się znaki nowego wiersza (\n) w ustrukturyzowanych danych wyjściowych
|
Gdy dane wejściowe modelu zawierają znaki Unicode lub sekwencje ucieczki, takie jak
\u lub \t, może to prowadzić do powtarzających się znaków nowego wiersza.
|
|
| Powtarzający się tekst w ustrukturyzowanych danych wyjściowych | Gdy dane wyjściowe modelu mają inną kolejność pól niż zdefiniowany schemat ustrukturyzowany, może to prowadzić do powtarzania się tekstu. |
|
| Powtarzające się wywoływanie narzędzia | Może się to zdarzyć, jeśli model utraci kontekst poprzednich myśli lub wywoła niedostępny punkt końcowy, do którego jest zmuszony. |
Poinstruuj model, aby zachowywał stan w procesie myślenia.
Dodaj ten tekst na końcu instrukcji systemowych:
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.
|
| Powtarzający się tekst, który nie jest częścią ustrukturyzowanych danych wyjściowych | Może się to zdarzyć, jeśli model utknie na żądaniu, którego nie może rozwiązać. |
|
Zablokowane lub niedziałające klucze interfejsu API
W tej sekcji opisujemy, jak sprawdzić, czy klucz Gemini API jest zablokowany, i co z tym zrobić.
Przyczyny blokowania kluczy
Zidentyfikowaliśmy lukę w zabezpieczeniach, w wyniku której niektóre klucze interfejsu API mogły zostać publicznie udostępnione. Aby chronić Twoje dane i zapobiegać nieautoryzowanemu dostępowi, proaktywnie zablokowaliśmy dostęp do Gemini API za pomocą tych znanych wyciekłych kluczy.
Sprawdzanie, czy problem dotyczy Twoich kluczy
Jeśli Twój klucz został ujawniony, nie możesz go już używać z Gemini API. W Google AI Studio możesz sprawdzić, czy któryś z Twoich kluczy interfejsu API jest zablokowany i nie może wywoływać Gemini API, oraz wygenerować nowe klucze. Podczas próby użycia tych kluczy możesz też zobaczyć ten błąd:
Your API key was reported as leaked. Please use another API key.
Działania w przypadku zablokowanych kluczy interfejsu API
W Google AI Studio wygeneruj nowe klucze interfejsu API na potrzeby integracji z Gemini API. Zdecydowanie zalecamy sprawdzenie metod zarządzania kluczami interfejsu API, aby upewnić się, że nowe klucze są bezpieczne i nie są publicznie udostępniane.
Nieoczekiwane opłaty spowodowane luką w zabezpieczeniach
Prześlij zgłoszenie do zespołu pomocy ds. płatności. Nasz zespół ds. płatności pracuje nad tym problemem i jak najszybciej poinformuje Cię o postępach.
Środki bezpieczeństwa Google w przypadku wyciekłych kluczy
Jak Google pomoże zabezpieczyć moje konto przed przekroczeniem kosztów i nadużyciami, jeśli moje klucze interfejsu API wyciekną?
- Wprowadzamy zmiany, aby klucze interfejsu API były wydawane tylko wtedy, gdy poprosisz o nowy klucz w Google AI Studio. Domyślnie będą one ograniczone tylko do Google AI Studio i nie będą akceptować kluczy z innych usług. Pomoże to zapobiec niezamierzonemu użyciu kluczy w różnych usługach.
- Domyślnie blokujemy klucze interfejsu API, które wyciekły i są używane z Gemini API, co pomaga zapobiegać nadużyciom związanym z kosztami i danymi aplikacji.
- Stan kluczy interfejsu API możesz sprawdzić w Google AI Studio. Będziemy też proaktywnie informować Cię, gdy wykryjemy, że Twoje klucze interfejsu API wyciekły, aby umożliwić Ci podjęcie natychmiastowych działań.
Poprawianie danych wyjściowych modelu
Aby uzyskać dane wyjściowe modelu o wyższej jakości, spróbuj pisać bardziej ustrukturyzowane prompty. Na stronie przewodnika po projektowaniu promptów znajdziesz podstawowe pojęcia, strategie i sprawdzone metody, które pomogą Ci zacząć.
Limity tokenów
Przeczytaj nasz przewodnik po tokenach, aby dowiedzieć się więcej o tym, jak liczyć tokeny i jakie są ich limity.
Znane problemy
- Interfejs API obsługuje tylko wybrane języki. Przesyłanie promptów w nieobsługiwanych językach może powodować nieoczekiwane lub nawet zablokowane odpowiedzi. Aktualne informacje znajdziesz na liście dostępnych języków.
Zgłaszanie błędu
Jeśli masz pytania, dołącz do dyskusji na forum dla deweloperów Google AI.