Błędy interfejsu API

Ta strona zawiera informacje o kodach błędów backendu zwracanych przez interfejs GenerateContent API, opisuje format odpowiedzi na błąd gRPC i zawiera kroki rozwiązywania problemów.

Kody błędów HTTP

W tabeli poniżej znajdziesz typowe kody błędów backendu, wyjaśnienia ich przyczyn i zalecane rozwiązania:

Kod HTTP Stan Opis Przykład Rozwiązanie
400 INVALID_ARGUMENT Treść żądania jest błędnie sformatowana. W żądaniu jest błąd w pisowni lub brakuje wymaganego pola. Format żądania, przykłady i obsługiwane wersje znajdziesz w dokumentacji API. Używanie funkcji z nowszej wersji interfejsu API ze starszym punktem końcowym może powodować błędy.
400 FAILED_PRECONDITION Bezpłatny poziom Gemini API nie jest dostępny w Twoim kraju. Włącz płatności w projekcie w Google AI Studio. Wysyłasz żądanie w regionie, w którym poziom bezpłatny nie jest obsługiwany, a w projekcie w Google AI Studio nie masz włączonych rozliczeń. Aby korzystać z Gemini API, musisz skonfigurować abonament w Google AI Studio.
402 RESOURCE_EXHAUSTED Saldo środków z przedpłaty zostało wyczerpane. Na Twoim koncie rozliczeniowym wyczerpały się środki przedpłaty, więc wszystkie klucze API powiązane z tym kontem rozliczeniowym przestają działać. Dodaj środki na konto rozliczeniowe lub włącz automatyczne doładowanie. Nie próbuj ponownie wysłać tego żądania: nie powiedzie się, dopóki nie dodasz środków.
403 PERMISSION_DENIED Twój klucz API nie ma wymaganych uprawnień. Używasz nieprawidłowego klucza interfejsu API. Próbujesz użyć dostosowanego modelu bez prawidłowego uwierzytelniania. Sprawdź, czy klucz interfejsu API jest ustawiony i ma odpowiedni dostęp. Aby korzystać z dostosowanych modeli, musisz przejść odpowiednią weryfikację.
404 NOT_FOUND Nie znaleziono żądanego zasobu. Nie znaleziono pliku obrazu, audio ani wideo, do którego odwołuje się Twoja prośba. Sprawdź, czy wszystkie parametry w żądaniu są prawidłowe w przypadku używanej wersji interfejsu API.
429 RESOURCE_EXHAUSTED Przekroczono jeden z limitów częstotliwości interfejsu API (RPM, TPM, RPD, wydatki itp.). Wysyłasz zbyt wiele żądań, używasz zbyt wielu tokenów lub przekraczasz limity oparte na wydatkach w przypadku historii płatności i poziomu konta. Sprawdź, czy nie przekraczasz limitów szybkości modelu. Poczekaj chwilę i spróbuj ponownie. Zmniejsz częstotliwość lub rozmiar żądań. W razie potrzeby poproś o zwiększenie limitu częstotliwości.
499 ANULOWANO Operacja została anulowana, zwykle przez element wywołujący. Klient zamknął połączenie, zanim interfejs API zdążył odpowiedzieć. Sprawdź, czy klient lub infrastruktura sieciowa przedwcześnie zamyka połączenie (np. z powodu limitu czasu po stronie klienta).
500 WEWNĘTRZNY Po stronie Google wystąpił nieoczekiwany błąd. Kontekst wejściowy jest za długi. Sprawdź stronę stanu Gemini API, aby dowiedzieć się o bieżących incydentach. 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 pomoże. Możesz też poczekać chwilę i ponowić prośbę. Jeśli problem będzie się powtarzać, zgłoś go, klikając przycisk 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 swoje możliwości. Sprawdź stronę stanu Gemini API, aby dowiedzieć się o bieżących incydentach. 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ć prośbę. Jeśli problem będzie się powtarzać, zgłoś go, klikając przycisk Prześlij opinię w Google AI Studio.
504 DEADLINE_EXCEEDED Usługa nie może zakończyć przetwarzania w terminie. Prompt (lub kontekst) jest zbyt duży, aby można go było przetworzyć na czas. Aby uniknąć tego błędu, ustaw w żądaniu klienta dłuższy „limit czasu”.

Format odpowiedzi na błąd

Gdy żądanie GenerateContent zakończy się niepowodzeniem, interfejs API ustawia kod stanu HTTP (np. 400 Bad Request, 403 Forbidden lub 429 Too Many Requests) i zwraca treść odpowiedzi JSON zawierającą szczegóły stanu gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Pole Typ Opis
code liczba całkowita Kod stanu HTTP.
message tekst Zrozumiały dla człowieka opis błędu.
status tekst Kod stanu gRPC w SCREAMING_CASE.
details tablica Dodatkowy kontekst błędu, np. ErrorInfo lub LocalizedMessage.

Co dalej?