Błędy API: przyczyny i rozwiązania
Każdy artykuł zaczyna się od odpowiedzi i podaje polecenie, którym sam potwierdzisz przyczynę. Komunikaty błędów zostawiliśmy w oryginale po angielsku – tak, jak pojawiają się w terminalu.
Unexpected token '<' przy wywołaniu API zgodnego z OpenAITwój klient dostał HTML zamiast JSON-a. Prawie zawsze w base URL brakuje /v1 albo występuje ono dwa razy. Jak potwierdzić to jednym poleceniem i jak naprawić.401 invalid API key – gdy klucz wygląda dobrze, a i tak nie działa401 przy kluczu, który przed chwilą skopiowałeś, zwykle wynika z białych znaków, złego nagłówka albo klucza, który nie ma dostępu do danego modelu. Jak ustalić, który to przypadek.404 na /v1/chat/completions, choć endpoint na pewno istnieje404 z endpointu, o którym wiesz, że działa, to prawie zawsze GET tam, gdzie API oczekuje POST, albo ścieżka przesunięta o jeden segment. Jak je od siebie odróżnić.Timeout 524 przy długich zapytaniach do API524 pochodzi z CDN przed API, a nie z modelu. Wyzwala się, gdy serwer źródłowy zbyt długo nic nie wysyła – dlatego zapytania ze streamingiem przeżywają, a bez streamingu nie.Model not found – gdy nazwa modelu jest prawie dobraTen błąd prawie zawsze oznacza, że nazwa modelu nie pasuje dokładnie albo twój klucz nie ma do niego dostępu. Jak wylistować to, co naprawdę możesz wywołać.429 z bramki API oznacza dwie różne rzeczyBramka zwraca 429 zarówno wtedy, gdy skończyło się saldo, jak i wtedy, gdy upstream jest przeciążony. Jedno warto ponawiać, drugiego nigdy. Jak odróżnić je po treści odpowiedzi.Błąd CORS przy wywołaniu API AI z przeglądarkiBłąd CORS to objaw. Prawdziwy problem polega na tym, że zapytanie z przeglądarki przekazuje twój klucz API każdemu odwiedzającemu. Co zrobić zamiast tego i dlaczego żadne ustawienie nagłówków tego nie naprawi.400 przy wymuszaniu wywołania narzędzia w modelu rozumującymUstawienie tool_choice na any lub tool jest odrzucane przez modele, które zawsze rozumują przed odpowiedzią. Co wysłać zamiast tego i jakie jeszcze parametry te modele odrzucają.Zapytania za Cloudflare padają dokładnie po 100 sekundachDługie generowanie pada niemal dokładnie po 100 sekundach z 524 albo urwanym streamem. Ta liczba to limit proxy Cloudflare, a nie twojego serwera. Jak to potwierdzić i trzy sposoby obejścia.Model zwraca pusty tekst, a i tak płaciszOdpowiedź przychodzi z HTTP 200, content jest pustym ciągiem, a w rozliczeniu widać naliczone tokeny wyjściowe. W modelach rozumujących to prawie zawsze max_tokens zużyte, zanim powstał jakikolwiek widoczny tekst.Odpowiedź strumieniowa urywa się w połowie zdaniaTokeny przychodzą, potem przestają, i nie pojawia się żaden błąd. Różnica między zakończonym a przerwanym strumieniem to jedna linia w treści SSE – a większość kodu klienta w ogóle jej nie sprawdza.Model, który wczoraj działał, dziś nie działa dla nikogo w tej samej grupie kluczyModel, który działał, zaczyna zwracać błędy dla każdego klucza w jednej grupie, a inne grupy działają normalnie. To kwestia routingu, nie modelu: jedno wadliwe konto upstream może położyć całą grupę.Rachunek jest wyższy, niż sugeruje liczba tokenówZalogowane sumy tokenów wyglądają skromnie, a opłata nie. W modelach z rodziny Claude zwykle chodzi o kierunek cache: zapis do cache kosztuje więcej niż zwykłe wejście, odczyt z cache – ułamek tego, a te same tokeny mogą różnić się ceną dwunastokrotnie.Claude Code i Codex potrzebują różnych base URL w tej samej bramceTa sama bramka, ten sam klucz, dwa agenty programistyczne – i base URL, który działa w jednym, a w drugim nie. Reguła jest prosta, gdy wiesz, który klient sam dopisuje ścieżkę.405 Method Not Allowed przy wywołaniu API AI405 na endpoincie AI prawie nigdy nie oznacza złej metody. Oznacza, że POST trafił tam, gdzie serwowane są tylko strony – zwykle na samą domenę, bo w base URL brakuje /v1. Jak to potwierdzić jednym poleceniem.404 na /responses – Responses API też potrzebuje prefiksu wersjiKlienci przechodzący z chat/completions na Responses API często gubią prefiks wersji. 404 przychodzi z brzegu sieci, zanim uruchomi się jakikolwiek kod API, więc wywołanie nigdy nie pojawia się w logu użycia.context_length_exceeded – co naprawdę wlicza się do limituLimit obejmuje całą rozmowę plus miejsce zarezerwowane na odpowiedź, a nie tylko ostatnią wiadomość. Dlaczego skracanie promptu często nie pomaga i co wyciąć zamiast tego.529 overloaded_error od Claude – co to jest i co zrobić529 oznacza, że upstream jest w tej chwili przeciążony. To nie problem limitu i nic, co twój klucz może naprawić. Jak odróżnić go od 429 i jaki schemat ponawiania naprawdę pomaga.401 z kluczem, który na pewno jest poprawny – sprawdź format nagłówkaKlucz może być całkowicie poprawny, a mimo to dawać 401, jeśli nagłówek jest źle zbudowany. Trzy sposoby, na jakie to się psuje, i jak zobaczyć nagłówek, który twój klient naprawdę wysłał.400 unsupported parameter w modelu rozumującymModele rozumujące odrzucają parametry próbkowania, które każdy inny model akceptuje. Które usunąć, dlaczego domyślna wartość i tak jest zwykle tym, czego chciałeś, i jak zachować jedną ścieżkę kodu dla obu rodzajów modeli.Brak zużycia tokenów w odpowiedzi strumieniowejOdpowiedź strumieniowa nie zawiera liczby tokenów, dopóki o nią nie poprosisz. Jak ją włączyć, gdzie przychodzi ostatni fragment i co zrobić, gdy bramka go nie wysyła.400 przy wywołaniu narzędzia – każde tool_use potrzebuje pasującego tool_resultBłąd pojawia się turę później niż pomyłka i to właśnie jest mylące. Reguła parowania, reguła kolejności i jak odtworzyć go celowo, żeby naprawić go raz na zawsze.Tryb JSON nadal zwraca tekst, którego nie da się sparsowaćresponse_format ogranicza kształt, a nie zakończenie. Ucięcie, brak egzekwowania schematu i tekst wokół obiektu psują parsowanie, każde na swój sposób.Wywołanie działa w curl, ale nie z twojej aplikacjiTen sam klucz, ten sam URL, inny wynik. Różnica prawie zawsze leży w czymś, czego curl nie robi: proxy, nieaktualna zmienna środowiskowa, ograniczenie IP albo biblioteka przepisująca twoje żądanie.SSL certificate verify failed przy wywołaniu API AIBłąd TLS z SDK przy działającym curl to prawie zawsze firmowe proxy albo antywirus, który ponownie podpisuje ruch. Dlaczego wyłączenie weryfikacji to zła naprawa i jakie trzy są właściwe.socket hang up w środku odpowiedzi strumieniowejStrumień, który zatrzymuje się w połowie, zostawia cię z niepełną odpowiedzią i bez błędu od modelu. Jak odróżnić zerwanie sieci od przerwania po stronie upstream i co zrobić w każdym przypadku.Claude Code: API Error 400 prompt is too longBłąd wskazuje na żądanie, ale przyczyną jest nagromadzony kontekst sesji: przeczytane pliki, wyniki narzędzi i historia rozmowy są wysyłane od nowa w każdej turze. Co wyczyścić, a co zostawić.Obraz wejściowy odrzucony przez model wizyjnyEndpointy wizyjne odrzucają obrazy z czterech różnych powodów, które dają niemal identyczne błędy. Jak je rozróżnić, zanim zaczniesz kodować wszystko od nowa.Prompt systemowy działa różnie w różnych modelachDwa dominujące kształty API umieszczają instrukcje systemowe w różnych miejscach. Kod napisany pod jeden po cichu działa gorzej z drugim zamiast zgłosić błąd – a to gorsze niż błąd.Jak poprawnie czytać 429 – retry-after i nagłówki limitówWiększość kodu ponawiającego zgaduje. Odpowiedź zwykle mówi dokładnie, ile czekać i który limit przekroczyłeś. Jak ją czytać i co zrobić, gdy nagłówka brakuje.Modele własnego endpointu nie pojawiają się na liście w kliencieKlienty desktopowe budują listę modeli na różne sposoby, a kilka z nich w ogóle nie wywołuje /v1/models. Jak rozpoznać, z którym rodzajem masz do czynienia, i co zrobić w każdym przypadku.Pusta odpowiedź z finish_reason content_filterPusta odpowiedź z powodem zakończenia content_filter oznacza, że zatrzymał ją system bezpieczeństwa. Jak odróżnić to od ucięcia i od prawdziwej awarii – i ile cię to kosztuje.Znaczniki czasu w logu użycia nie zgadzają się z czasem wywołaniaWywołanie, które pojawia się kilka godzin od momentu, w którym je wykonałeś, to prawie zawsze różnica stref czasowych, a nie zgubiony wpis. Jak to wyrównać, zanim zgłosisz problem z rozliczeniem.Podwójna opłata za coś, co wyglądało na jedno żądanieLimit czasu po stronie klienta nie zatrzymuje pracy, która już trwa na serwerze. Typowy przebieg przypadkowej podwójnej opłaty i dwie zmiany, które jej zapobiegają.