Błędy interfejsu API

Ta strona zawiera informacje o wszystkich kodach błędów interfejsu Interactions API, opisuje format odpowiedzi na błąd i wyjaśnia, jak interfejs API dostarcza błędy w przypadku różnych typów żądań.

Standardowe kody błędów interfejsu API

Te ogólne kody błędów na poziomie żądania odpowiadają standardowym kodom stanu HTTP. Aby programowo obsługiwać błędy, użyj pola code w logice aplikacji.

Kod Stan HTTP Opis Zalecane działanie
invalid_request 400 Nieprawidłowe żądanie Treść żądania jest nieprawidłowa lub zawiera nieprawidłowe parametry. Sprawdź składnię i parametry żądania w dokumentacji interfejsu API.
failed_precondition 400 Nieprawidłowe żądanie Nie można przetworzyć żądania, ponieważ nie został spełniony warunek wstępny (np. wyłączone rozliczenia). Sprawdź stan rozliczeń projektu lub wymagania wstępne dotyczące konta.
out_of_range 416 Zakres żądania nie do obsłużenia Parametr żądania jest poza prawidłowym zakresem. Sprawdź wartości parametrów i limity.
parameter_unknown 400 Nieprawidłowe żądanie Żądanie zawiera nieznany parametr. Usuń nierozpoznany parametr i spróbuj ponownie.
authentication 401 Brak autoryzacji Brak klucza interfejsu API, jest on nieprawidłowy lub wygasł. Sprawdź kl0}ucz interfejsu API.
permission_denied 403 Dostęp zabroniony Twój klucz interfejsu API nie ma uprawnień do tego zasobu. Sprawdź uprawnienia klucza interfejsu API i dostęp do projektu.
not_found 404 Nie znaleziono Nie znaleziono żądanego zasobu. Sprawdź ścieżkę zasobu i parametry.
model_not_found 404 Nie znaleziono Nie znaleziono określonego modelu. Sprawdź nazwę modelu lub przejdź na inny model.
already_exists 409 Konflikt Encja, którą próbujesz utworzyć, już istnieje. Zanim ponownie utworzysz zasób, sprawdź, czy już istnieje.
aborted 409 Konflikt Operacja została przerwana z powodu konfliktu lub nieudanej weryfikacji współbieżności. Ponów próbę na wyższym poziomie aplikacji.
rate_limit_exceeded 429 Zbyt wiele żądań Przekroczono limit żądań lub tokenów na minutę lub sekundę. Poczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
quota_exceeded 429 Zbyt wiele żądań Przekroczono dzienny limit. Poczekaj, aż limit się zresetuje, lub poproś o jego zwiększenie.
too_many_requests 429 Zbyt wiele żądań W krótkim czasie wysłano zbyt wiele żądań. Poczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
cancelled 499 Klient zamknął żądanie Klient anulował żądanie przed jego zakończeniem. Nie musisz niczego robić. Zwykle oznacza to, że klient się rozłączył.
api_error 500 Wewnętrzny błąd serwera Na serwerze wystąpił nieoczekiwany błąd. Ponów próbę. Jeśli problem się powtórzy, skontaktuj się z zespołem pomocy.
unimplemented 501 Nie zaimplementowano Operacja lub funkcja nie jest zaimplementowana ani obsługiwana. Sprawdź możliwości interfejsu API lub przejdź na obsługiwaną funkcję.
service_unavailable 503 Usługa niedostępna Usługa jest tymczasowo przeciążona lub niedostępna. Poczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
deadline_exceeded 504 Przekroczono limit czasu bramy Nie udało się przesłać prośby w wyznaczonym czasie. Usuń lub zwiększ limit czasu klienta, aby użyć ustawienia domyślnego serwera.

Kody wskazujące na zablokowanie generowania

Te kody błędów wskazują, że dane wyjściowe modelu zostały zablokowane przez ograniczenia dotyczące zasad, bezpieczeństwa lub ograniczenia treści. Gdy otrzymasz jeden z tych kodów, zmodyfikuj dane wejściowe i spróbuj ponownie.

Kod Opis
safety Żądanie zostało zablokowane z powodu naruszenia zasad bezpieczeństwa (szkodliwe treści).
recitation Żądanie zostało zablokowane z powodu ograniczeń dotyczących praw autorskich lub recytacji.
language Żądanie zostało zablokowane z powodu nieobsługiwanego języka.
prohibited_content Żądanie zostało zablokowane z powodu wytycznych dotyczących niedozwolonych treści.
spii Żądanie zostało zablokowane z powodu ograniczeń dotyczących informacji poufnych umożliwiających identyfikację.
blocklist Żądanie zostało zablokowane z powodu niedozwolonych terminów na liście zablokowanych.
image_safety Generowanie obrazu zostało zablokowane z powodu naruszenia zasad bezpieczeństwa.
image_prohibited_content Generowanie obrazu zostało zablokowane z powodu wytycznych dotyczących niedozwolonych treści.
image_recitation Generowanie obrazu zostało zablokowane z powodu ograniczeń dotyczących praw autorskich lub recytacji.
image_other Generowanie obrazu zostało zablokowane z nieokreślonych powodów.
content_blocked Żądanie zostało zablokowane z nieokreślonego powodu związanego z zasadami.

Kody błędów generowania

Te kody błędów wskazują na problem strukturalny z wygenerowanymi danymi wyjściowymi modelu (np. nieprawidłowe wywołanie funkcji lub niezadeklarowane wywołanie narzędzia).

Kod Opis
malformed_function_call Model wygenerował wywołanie funkcji, którego nie udało się przeanalizować.
malformed_tool_call Model wygenerował wywołanie narzędzia, którego nie udało się przeanalizować.
unexpected_tool_call Model wywołał narzędzie, które nie zostało zadeklarowane w żądaniu.
no_image Model nie mógł wygenerować obrazu.
too_many_tool_calls Model wygenerował więcej wywołań narzędzi niż jest to dozwolone.
missing_thought_signature W odpowiedzi brakuje wymaganego podpisu.

Format odpowiedzi na błąd

Wszystkie błędy z interfejsu Interactions API zwracają obiekt error zawierający code i message. Na przykład przekazanie nieobsługiwanego typu narzędzia zwraca:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Pole Typ Opis
code tekst Kod błędu w formacie snake_case.
message tekst Zrozumiały dla człowieka opis problemu.

Jak są dostarczane błędy

Interfejs API dostarcza błędy w różny sposób w zależności od tego, czy wysyłasz standardowe żądanie HTTP, czy żądanie strumieniowe (SSE).

Standardowe żądania HTTP

W przypadku standardowych (niestrumieniowych) żądań interfejs API ustawia kod stanu odpowiedzi HTTP (np. 400 Bad Request, 401 Unauthorized, lub 429 Too Many Requests) i zwraca obiekt error w treści odpowiedzi JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Żądania strumieniowe (SSE)

W przypadku żądań strumieniowych (stream: true) interfejs API wysyła zdarzenia błędów w strumieniu Server-Sent Events (SSE) z ustawionym parametrem event_type na wartość "error". Pole error zawiera tę samą strukturę code i message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Pełny schemat zdarzeń SSE znajdziesz w dokumentacji interfejsu Interactions API.

Co dalej?