Błędy interfejsu API

Ta strona zawiera odniesienie do wszystkich kodów błędów interfejsu Interactions API, opisuje format odpowiedzi z błędem 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. Użyj pola code w logice aplikacji, aby programowo obsługiwać błędy.

Kod Stan HTTP Opis Zalecane działanie
invalid_request 400 Nieprawidłowe żądanie Ładunek żądania jest nieprawidłowy 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 wykracza poza prawidłowy zakres. Sprawdź wartości i limity parametrów.
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ź klucz interfejsu API.
payment_required 402 Wymagana płatność Saldo środków z przedpłaty zostało wyczerpane. Dodaj środki na konto rozliczeniowe lub włącz automatyczne doładowanie. Nie ponawiaj próby: prośba nie zostanie zrealizowana, dopóki nie dodasz środków.
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 Błąd 404 (nie znaleziono) Nie znaleziono żądanego zasobu. Sprawdź ścieżkę zasobu i parametry.
model_not_found Błąd 404 (nie znaleziono) Nie znaleziono podanego modelu. Sprawdź nazwę modelu lub użyj innego.
already_exists 409 Konflikt Encja, którą próbujesz utworzyć, już istnieje. Przed ponownym utworzeniem sprawdź, czy zasób już istnieje.
aborted 409 Konflikt Operacja została przerwana z powodu konfliktu lub nieudanej kontroli równoczesności. Ponów prośbę na wyższym poziomie aplikacji.
rate_limit_exceeded 429 Zbyt wiele żądań Przekroczono limit żądań lub tokenów na minutę lub sekundę. Zaczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
quota_exceeded 429 Zbyt wiele żądań Dzienny limit został przekroczony. 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ń. Zaczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
cancelled 499 Klient zamknął żądanie Klient anulował żądanie przed jego ukończeniem. Nie musisz niczego robić. Zwykle oznacza to, że klient został odłączony.
api_error 500 Wewnętrzny błąd serwera Na serwerze wystąpił nieoczekiwany błąd. Ponów prośbę. Jeśli problem będzie się powtarzać, 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 przełącz się na obsługiwaną funkcję.
service_unavailable 503 Usługa niedostępna Usługa jest tymczasowo przeciążona lub niedostępna. Zaczekaj i spróbuj ponownie ze wzrastającym czasem do ponowienia.
deadline_exceeded 504 Przekroczono limit czasu bramy Prośba nie została zrealizowana w terminie. Usuń lub zwiększ ustawienie terminu klienta, aby używać domyślnego terminu serwera.

Kody zablokowane podczas generowania

Te kody błędów wskazują, że ograniczenia dotyczące zasad, bezpieczeństwa lub treści zablokowały dane wyjściowe modelu. Gdy otrzymasz jeden z tych kodów, zmień 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ń wynikających z praw autorskich lub praw do recytacji.
language Żądanie zostało zablokowane z powodu nieobsługiwanego języka.
prohibited_content Żądanie zostało zablokowane przez wytyczne dotyczące niedozwolonych treści.
spii Ograniczenia dotyczące informacji poufnych umożliwiających identyfikację zablokowały prośbę.
blocklist Żądanie zostało zablokowane, ponieważ na liście zablokowanych haseł znajdowały się niedozwolone słowa.
image_safety Generowanie obrazu zostało zablokowane z powodu naruszenia zasad bezpieczeństwa.
image_prohibited_content Wytyczne dotyczące niedozwolonych treści zablokowały generowanie obrazu.
image_recitation Ograniczenia wynikające z praw autorskich lub recytacji zablokowały generowanie obrazu.
image_other Z nieokreślonych powodów generowanie obrazu zostało zablokowane.
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łowo sformułowane wywołanie funkcji lub niezadeklarowane wywołanie narzędzia).

Kod Opis
malformed_function_call Model wygenerował wywołanie funkcji, którego nie można było 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 był w stanie 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 czytelnym dla komputera w języku snake_case.
message tekst Zrozumiały dla człowieka opis tego, co poszło nie tak.

Jak są dostarczane błędy

Interfejs API zwraca błędy w różny sposób w zależności od tego, czy wysyłasz standardowe żądanie HTTP czy żądanie przesyłania strumieniowego (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 strumieniowania (SSE)

W przypadku żądań strumieniowania (stream: true) interfejs API wysyła zdarzenia błędów w strumieniu zdarzeń wysyłanych przez serwer (SSE) z parametrem event_type ustawionym na "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 API interakcji.

Co dalej?