Błędy 429 slow_down i 503 w OpenAI API. Jak je rozpoznać i obsłużyć

Co zmieniło się 2 września

Do września 2026 roku programista widział zwykle ten sam status HTTP 429 w kilku różnych sytuacjach: przy przekroczeniu limitu zapytań, przy braku środków na koncie i przy chwilowych problemach z wydajnością. Wpis w dzienniku zmian OpenAI API z 2 września 2026 roku wprowadził wyraźniejszy podział. Zbyt szybki wzrost ruchu zwraca 429 z kodem slow_down, a chwilowe przeciążenie modelu zwraca 503 z kodem server_is_overloaded.

Zmiana ma znaczenie dla monitoringu i alertów. Pierwszy błąd wynika z zachowania aplikacji klienta, drugi z sytuacji po stronie OpenAI. Po rozdzieleniu kodów zespół może reagować inaczej: w pierwszym przypadku spowolnić własny ruch, w drugim sprawdzić status usługi i ewentualnie przełączyć zadanie na inny model.

Rodzaje błędu 429 w OpenAI API

Status 429 obejmuje obecnie kilka przypadków o różnych przyczynach. Część z nich dotyczy tempa zapytań, a część rozliczeń. Poniższa lista porządkuje je według dokumentacji kodów błędów OpenAI.

• slow_down (typ rate_limit_error) - ruch rośnie szybciej, niż usługa to toleruje. Rozwiązanie: respektować Retry-After i zwiększać ruch stopniowo.
• Rate limit reached for requests - przekroczony limit zapytań lub tokenów na minutę. Rozwiązanie: rozłożyć zapytania w czasie, stosować backoff, sprawdzić zużycie całego zespołu.
• credit_balance_exhausted - wyczerpane środki przedpłacone. Rozwiązanie: doładować saldo w ustawieniach rozliczeń.
• organization_spend_limit_exceeded - przekroczony miesięczny limit wydatków organizacji. Rozwiązanie: podnieść albo usunąć limit w ustawieniach organizacji.
• project_spend_limit_exceeded - przekroczony limit jednego projektu. Rozwiązanie: zmienić limit w projekcie, pozostałe projekty działają dalej.
• organization_usage_limit_exceeded - przekroczony próg przyznany przez OpenAI. Rozwiązanie: wystąpić o wyższy limit lub skontaktować się z pomocą techniczną.

Dlaczego slow_down pojawia się mimo wolnego limitu

Limity RPM (zapytania na minutę) i TPM (tokeny na minutę) określają maksymalny poziom ruchu. Kod slow_down dotyczy innej rzeczy: tempa, w jakim ten ruch rośnie. Aplikacja może więc mieścić się w przyznanym limicie, a mimo to dostać błąd, jeśli w ciągu kilku minut kilkukrotnie zwiększy liczbę zapytań.

Dokumentacja podaje konkretną regułę. Po osiągnięciu 1 mln tokenów wejściowych na minutę ruch należy zwiększać najwyżej o 50 proc. co 15 minut. Przykład: usługa przetwarzająca 1 mln tokenów na minutę może po kwadransie dojść do 1,5 mln, a po kolejnym do 2,25 mln. Skok od razu do 3 mln, na przykład po uruchomieniu nocnego przetwarzania całej bazy dokumentów, zwiększa ryzyko błędu slow_down.

Problem dotyczy więc głównie większych wdrożeń: kampanii marketingowych, migracji danych, jednorazowego przetwarzania archiwum czy premier funkcji z nagłym napływem użytkowników. Mała aplikacja z ruchem rzędu kilkudziesięciu zapytań na minutę rzadko zbliży się do tego progu.

Błąd 503 server_is_overloaded

Kod server_is_overloaded (typ service_unavailable_error) oznacza, że wybrany model nie ma w danej chwili wolnej mocy obliczeniowej. Przyczyna leży po stronie OpenAI, więc zmiana ustawień konta nic nie da. Dokumentacja zaleca respektowanie nagłówka Retry-After, wydłużanie przerw między kolejnymi próbami i sprawdzenie strony statusu usługi.

W naszej ocenie przy tym błędzie warto mieć przygotowany wariant awaryjny. Dla zadań, które nie wymagają najmocniejszego modelu, może to być przełączenie na tańszy lub mniej obciążony model tej samej rodziny. Zadania bez presji czasu lepiej odłożyć do kolejki niż ponawiać w pętli.

Jak poprawnie ponawiać zapytania

Wszystkie oficjalne biblioteki OpenAI automatycznie ponawiają kwalifikujące się odpowiedzi 429 i 503 zgodnie z ustawieniami klienta. Własna logika jest potrzebna wtedy, gdy aplikacja korzysta z bezpośrednich wywołań HTTP, ma nietypowe wymagania czasowe albo wysyła duże partie zapytań równolegle. Poniższa procedura odpowiada zaleceniom z dokumentacji limitów.

1. Odczytaj kod błędu z treści odpowiedzi, a nie tylko status HTTP. Inaczej obsłuż slow_down, server_is_overloaded i błędy rozliczeniowe.
2. Błędów credit_balance_exhausted i przekroczonych limitów wydatków nie ponawiaj. Zgłoś alert do osoby odpowiedzialnej za rozliczenia.
3. Jeśli odpowiedź zawiera nagłówek Retry-After, czekaj co najmniej tyle sekund, ile wskazuje.
4. Bez tego nagłówka stosuj wykładniczy backoff, czyli podwajanie przerwy po każdej nieudanej próbie, z losowym rozrzutem (jitter).
5. Ogranicz zarówno liczbę prób, jak i łączny czas ponawiania, aby zapytanie nie blokowało kolejki bez końca.
6. Po serii błędów slow_down zmniejsz tempo wysyłki całej usługi, a nie tylko pojedynczego zapytania, i zwiększaj je stopniowo.
7. Monitoruj nagłówki x-ratelimit-remaining-requests i x-ratelimit-remaining-tokens, aby zwalniać ruch, zanim pojawi się błąd.

Ograniczenia i sposoby na duży ruch

Losowy rozrzut przy ponawianiu nie jest dodatkiem kosmetycznym. Jeśli setki procesów dostaną błąd w tej samej sekundzie i odczekają identyczny czas, uderzą w API jednocześnie i sytuacja się powtórzy. Rozrzut rozkłada ponowienia w czasie.

Dla zadań, które nie muszą kończyć się od razu, OpenAI wskazuje Batch API. Zapytania wysłane w ten sposób nie zużywają synchronicznych limitów, a limity kolejki liczone są na podstawie łącznej liczby tokenów wejściowych oczekujących dla danego modelu. Duże organizacje, które regularnie trafiają na limit tempa wzrostu, mogą rozważyć Scale Tier dla ruchu rozliczanego na bieżąco albo Reserved Tier dla GPT-5.6 i nowszych modeli. Oba warianty zapewniają bardziej przewidywalną moc obliczeniową.

Dokumentacja nie podaje progu tempa wzrostu dla ruchu poniżej 1 mln tokenów na minutę. Nie oznacza to, że przy mniejszej skali błąd slow_down nie wystąpi, dlatego obsługa tego kodu powinna trafić do każdej aplikacji produkcyjnej.

Co to oznacza dla polskich zespołów

Polskie firmy korzystające z OpenAI API najczęściej działają w niższych progach użycia. Poziom dostępu rośnie automatycznie wraz z wydatkami: próg Tier 1 wymaga zapłaty 5 USD, a Tier 5 zapłaty 1000 USD. Wyższy poziom oznacza wyższe limity, ale nie znosi zasady stopniowego zwiększania ruchu.

Rozdzielenie kodów błędów ułatwia też raportowanie incydentów. Jeśli w logach dominuje server_is_overloaded, problem leży po stronie dostawcy i warto odnotować go w rozmowie o SLA z klientem. Jeśli dominuje slow_down, przyczyną jest sposób wysyłania ruchu przez własną aplikację, a rozwiązanie leży w kodzie i harmonogramie zadań.

Zmianę warto połączyć z przeglądem zabezpieczeń konta. Limity wydatków na poziomie projektu chronią przed niekontrolowanym kosztem, a osobne klucze dla usług pozwalają szybciej ustalić, która z nich generuje nagły wzrost ruchu.