Błędy interfejsu API

Na tej stronie znajdziesz informacje o kodach błędów backendu zwracanych przez interfejs GenerateContent API, opis formatu odpowiedzi na błąd gRPC oraz instrukcje rozwiązywania problemów.

Kody błędów HTTP

W tabeli poniżej znajdziesz listę typowych kodów błędów backendu, wyjaśnienia ich przyczyn oraz zalecane rozwiązania:

Kod HTTP Stan Opis Przykład Rozwiązanie
400 INVALID_ARGUMENT Treść żądania jest błędnie sformatowana. 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; próbujesz użyć 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 korzystać z 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 używanej wersji interfejsu API.
429 RESOURCE_EXHAUSTED Przekroczono jeden z limitów częstotliwości żądań 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 historii płatności i poziomie konta. Sprawdź, czy nie przekraczasz limitów częstotliwości żądań modelu. Odczekaj chwilę i spróbuj ponownie. Zmniejsz częstotliwość lub rozmiar żądań. W razie potrzeby poproś o zwiększenie limitu częstotliwości żądań.
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 większy „limit czasu” w żądaniu klienta.

Format odpowiedzi na błąd

Gdy żądanie GenerateContent nie powiedzie się, 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 Opis błędu w języku naturalnym.
status tekst Kod stanu gRPC w formacie SCREAMING_CASE.
details tablica Dodatkowy kontekst błędu, np. ErrorInfo lub LocalizedMessage.

Co dalej?