Błędy interfejsu API

Na tej stronie znajdziesz informacje o wszystkich kodach błędów interfejsu Interactions API, opis formatu odpowiedzi na błąd oraz wyjaśnienie, 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 obsługiwać błędy automatycznie, użyj pola code w logice aplikacji.

Kod Stan HTTP Opis Zalecane działanie
invalid_request 400 Nieprawidłowe żądanie Ładunek żądania jest nieprawidłowo sformatowany 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 płatności za projekt lub wymagania wstępne dotyczące konta.
out_of_range 416 Zakres bajtowy podany w żądaniu 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 opłata Saldo środków na koncie z przedpłaty zostało wyczerpane. Dodaj środki do konta rozliczeniowego lub włącz automatyczne doładowanie. Nie ponawiaj próby: żądanie nie powiedzie się, dopóki nie zostaną dodane środki.
permission_denied 403 Dostęp zabroniony Twój klucz interfejsu API nie ma uprawnień do tego zasobu lub dostęp do interfejsu API w projekcie jest ograniczony. Sprawdź uprawnienia klucza interfejsu API, poziom projektu i stan płatności. Zobacz Rozwiązywanie problemów z projektem, który jest ograniczony lub niedostępny.
not_found Błąd 404 (nie znaleziono) Nie znaleziono żądanego zasobu. Sprawdź ścieżkę i parametry zasobu.
model_not_found Błąd 404 (nie znaleziono) Nie znaleziono określonego modelu. Sprawdź nazwę modelu lub użyj innego modelu.
already_exists 409 Conflict Encja, którą próbujesz utworzyć, już istnieje. Przed ponownym utworzeniem zasobu sprawdź, czy już nie istnieje.
aborted 409 Conflict Operacja została przerwana z powodu konfliktu lub nieudanej kontroli równoczesności. Ponów żądanie na wyższym poziomie aplikacji.
rate_limit_exceeded 429 Too Many Requests (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 Too Many Requests (Zbyt wiele żądań) Przekroczono dzienny limit. Poczekaj, aż limit zostanie zresetowany, lub poproś o jego zwiększenie.
too_many_requests 429 Too Many Requests (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, zanim zostało ono zrealizowane. Nie musisz nic robić. Zwykle oznacza to, że klient się rozłączył.
api_error 500: Wewnętrzny błąd serwera Na serwerze wystąpił nieoczekiwany błąd. Spróbuj ponownie przesłać 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 lub 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 Żądanie nie zostało zrealizowane w terminie. Usuń lub zwiększ ustawienie terminu klienta, aby używać domyślnego ustawienia serwera.

Kody blokowania generowania

Te kody błędów wskazują, że dane wyjściowe modelu zostały zablokowane przez zasady, zabezpieczenia lub ograniczenia treści. Jeśli 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 ze względu na ograniczenia dotyczące praw autorskich lub recytacji.
language Żądanie zostało zablokowane z powodu nieobsługiwanego języka.
prohibited_content Żądanie zostało zablokowane ze względu na wytyczne dotyczące niedozwolonych treści.
spii Żądanie zostało zablokowane przez ograniczenia dotyczące informacji poufnych umożliwiających identyfikację.
blocklist Żądanie zostało zablokowane przez niedozwolone hasła na liście zablokowanych.
image_safety Naruszenia zasad bezpieczeństwa zablokowały generowanie obrazu.
image_prohibited_content Wytyczne dotyczące niedozwolonych treści zablokowały generowanie obrazów.
image_recitation Generowanie obrazu zostało zablokowane ze względu na ograniczenia dotyczące praw autorskich lub cytowania.
image_other Nieokreślone przyczyny zablokowały generowanie obrazu.
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 danymi wyjściowymi wygenerowanymi przez model (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 dozwolone.
missing_thought_signature W odpowiedzi brakuje wymaganego podpisu myśli.

Format odpowiedzi na błąd

Wszystkie błędy z 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 komputerów w: snake_case.
message tekst Zrozumiały dla człowieka opis błędu.

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 żądań (niestrumieniowych) 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 przez strumień 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 Interactions API.

Co dalej?