Błędy i ponawianie żądań
Rozpoznaj status HTTP lub błąd strumienia i wybierz właściwy kolejny krok.
Zapisz x-request-id, zanim odczytasz treść odpowiedzi. Jeśli strumień się urwie, zachowaj nagłówki HTTP i ewentualne końcowe zdarzenie błędu. W Analytics → Requests sprawdź zapisany wynik i przyczynę błędu; błędy przed uwierzytelnieniem mogą nie mieć wpisu w historii konta.
Struktura błędu
Chat Completions używa struktury zgodnej z OpenAI. Poniższy przykład oznacza brak klucza bramy API lub niepoprawny klucz:
{
"error": {
"message": "A valid API key is required",
"type": "invalid_api_key",
"param": null,
"code": "invalid_api_key"
}
}Messages zwraca ten sam błąd w strukturze zgodnej z Anthropic:
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "A valid API key is required"
}
}Dla HTTP 402 odpowiedzi OpenAI używają insufficient_credits, a odpowiedzi Anthropic — billing_error. Ten status może oznaczać zarówno za mało kredytów, jak i miesięczny limit klucza. Rozróżnisz je po komunikacie wygenerowanym przez bramę. Treść błędu dostawcy jest zastępowana bezpiecznym komunikatem, a nie kopiowana do odpowiedzi.
Status, przyczyna i działanie
| Status | Typowa przyczyna | Co zrobić |
|---|---|---|
400 | Niepoprawne pole, nieobsługiwana opcja, zbyt duże wejście lub budżet odpowiedzi ponad limit modelu | Sprawdź param, jeśli występuje, usuń odrzuconą funkcję albo zmniejsz wejście lub budżet odpowiedzi. |
401 | Brak, niepoprawny lub unieważniony klucz bramy; status może też wystąpić po wyczerpaniu prób wskutek błędu uwierzytelniania dostawcy | Użyj zapisanego aktywnego klucza albo utwórz nowy w API Keys. Jeśli inne wywołania z tym kluczem działają, zachowaj ID żądania i sprawdź wpis błędu. |
402 | Za mało dostępnych kredytów lub przekroczenie miesięcznego limitu klucza | Sprawdź Credits, aktywne blokady środków i ustawienia API Keys. W razie potrzeby zmniejsz budżet odpowiedzi. |
403 | Model wykluczony przez listę klucza lub filtry routingu konta | Zezwól na model w obu miejscach. Żadne z ustawień nie omija drugiego. |
404 | Nieznany model lub nieobsługiwana trasa | Skopiuj ID modelu z Marketplace. Użyj jednego z czterech publicznych endpointów. |
408 | Klient przestaje czytać strumień na tyle długo, że połączenie zostaje zamknięte | Odbieraj strumień na bieżąco; sprawdź buforowanie klienta lub proxy. Status może być widoczny w historii po zakończeniu połączenia. |
409 | Nie można rozliczyć zużycia lub blokady żądania przy obecnej dostępnej pojemności | Przed ponowieniem sprawdź Requests i kredyty; jeśli wynik jest niejasny, podaj ID żądania w zgłoszeniu. |
413 | Treść żądania przekracza dopuszczalny rozmiar | Zmniejsz treść, dane obrazów lub historię rozmowy. |
429 | Limit częstotliwości klucza lub dostawcy | Uwzględnij Retry-After, jeśli występuje, i ogranicz liczbę równoległych wywołań. |
499 | Klient rozłącza się przed zakończeniem | Sprawdź anulowanie żądań i limity czasu klienta. To zapisany wynik; rozłączony klient nie otrzyma go jako nowej odpowiedzi HTTP. |
500 | Dostawca lub brama nie może zakończyć żądania | Sprawdź historię przed ograniczoną liczbą ponownych prób; zachowaj ID żądania. |
502 | Niepoprawna odpowiedź dostawcy lub nagle zakończony strumień | Sprawdź, czy otrzymałeś część odpowiedzi, i w razie potrzeby ponów żądanie po przerwie. |
503 | Brak odpowiedniej oferty, wyczerpana pojemność, chwilowe przeciążenie lub brak oferty gotowej do obsługi żądania | Sprawdź Marketplace, filtry modeli i limit ceny. Uwzględnij Retry-After, jeśli występuje. Obsługiwane błędy 503 żądań generowania odpowiedzi zawierają Retry-After: 1 przed rozpoczęciem strumienia; nie zakładaj tego dla każdego endpointu. |
504 | Przekroczony czas dostawcy lub całego żądania | Sprawdź, czy korzystałeś ze strumienia i czy pojawiła się część odpowiedzi. W razie potrzeby ponów żądanie z ograniczonym budżetem. |
529 | Przeciążenie dostawcy | Odczekaj i spróbuj później; dostępność nie jest gwarantowana. |
Dokładny typ błędu zależy od formatu odpowiedzi. Ogólne api_error nie wskazuje kodu błędu konkretnego dostawcy.
Ponawianie strumieni
Przed wysłaniem bajtów odpowiedzi brama może użyć fallbacku, czyli wypróbować inną ofertę — łącznie najwyżej trzy. Gdy odpowiedź już się zacznie, błąd jest zdarzeniem w istniejącym strumieniu, a nie nowym statusem HTTP ani przełączeniem sprzedawcy. Strumień OpenAI przenosi obiekt błędu w zdarzeniu data:, a Anthropic używa event: error.
Traktuj częściowy wynik jako niekompletny. Ponowienie tworzy nowe żądanie i może naliczyć kolejną opłatę. SDK również mogą automatycznie ponawiać wywołania; ogranicz liczbę prób i zapisuj każde ID żądania. Jeśli agent zdążył uruchomić narzędzie zmieniające dane, sprawdź wynik, zanim pozwolisz mu powtórzyć działanie.
Zgłoś problem
Podaj x-request-id, przybliżony czas UTC, ID modelu, nazwę i wersję klienta, endpoint oraz informację o użyciu strumienia. Dołącz bezpieczny komunikat błędu lub przyczynę niepowodzenia i napisz, czy dotarła część odpowiedzi. Nie wysyłaj klucza API, danych dostawcy ani prywatnej treści promptu.