Przejdź do głównej treści
Polski— Wybierz język
Menu

Obsługa błędów i kody HTTP

Lekcja 12 z 22 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Obsługa błędów i kody HTTP
  2. Kody HTTP API OpenAI
  3. Kompleksowa obsługa błędów
  4. Specyficzne błędy Responses API
  5. Strukturalne logowanie błędów
  6. Tabela podsumowująca
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane tylko przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie przeprowadzają rozumowanie (medium). Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Wyjaśniono 3 listopada 2026 r. na podstawie strony Deprecations firmy OpenAI: usunięty wcześniej przykład modelu używał gpt-4o, który pozostaje dostępny do 14 stycznia 2027 r.; obecnie używa gpt-4-turbo, który został wycofany 23 października 2026 r. (wskazany zamiennik: gpt-5.6-sol). Źródło: Deprecations.

Obsługa błędów i kody HTTP

W środowisku produkcyjnym błędy są nieuniknione. Sieć może zawieść, klucz API wygasnąć, współpracownik wdrożyć nieprawidłowy parametr lub samo API może doświadczyć trzyminutowej przerwy w działaniu. Zrozumienie kodów HTTP zwracanych przez API i ich prawidłowa obsługa są kluczowe dla budowania odpornych aplikacji. Całe wyzwanie sprowadza się do jednego pytania, które musisz zadać przy każdym wyjątku: czy ten problem zniknie, jeśli ponowię próbę, czy też będę wpadać w nieskończoną pętlę z problemem, który może rozwiązać tylko człowiek?

Kody HTTP API OpenAI

API zwraca standardowe kody HTTP, aby wskazać wynik każdego żądania. Python SDK nie pozwala na ręczne obsługiwanie tych kodów; zamiast tego tłumaczy każdy z nich na typowany wyjątek, który możesz przechwycić osobno. Pozwala to na pisanie precyzyjnych bloków except, zamiast stosować łapiący wszystko except Exception, który zatarłby naturę problemu.

from openai import OpenAI
from openai import (
    APIError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    APIConnectionError,
    InternalServerError,
    PermissionDeniedError,
    NotFoundError,
    UnprocessableEntityError,
)

client = OpenAI()

401 — AuthenticationError

Kod 401 oznacza, że klucz API jest nieprawidłowy lub brakujący. Zazwyczaj widzisz to podczas pierwszego wdrożenia, gdy zmienna środowiskowa nie została przekazana do kontenera. Ponawianie próby jest bezcelowe: za dziesięć sekund klucz będzie równie nieprawidłowy.

try:
    # Nieprawidłowy lub brakujący klucz API
    bad_client = OpenAI(api_key="sk-invalid")
    bad_client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except AuthenticationError as e:
    print(f"Code: {e.status_code}")  # 401
    print(f"Message: {e.message}")
    # Działanie: zweryfikuj klucz API, w razie potrzeby wygeneruj go ponownie

400 — BadRequestError

Kod 400 informuje, że żądanie jest niepoprawnie sformatowane. Tutaj podano temperaturę 5.0, podczas gdy maksymalna akceptowana wartość to 2.0. Komunikat o błędzie prawie zawsze wskazuje wadliwy parametr, co czyni ten błąd najszybszym do naprawienia – pod warunkiem, że go prawidłowo zalogujesz, zamiast go po cichu ignorować.

try:
    # Nieprawidłowe parametry
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperatura wymaga effort none
        input="Test",
        temperature=5.0  # Nieprawidłowa wartość (maks. 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Działanie: popraw parametry żądania

429 — RateLimitError

Kod 429 oznacza, że wysyłasz zbyt wiele żądań lub przekroczyłeś swój limit (quota). W przeciwieństwie do dwóch poprzednich, ten błąd ma charakter tymczasowy: licznik się resetuje. To podręcznikowy przypadek do ponowienia próby, ale takiej, która czeka – i czeka coraz dłużej z każdą kolejną próbą.

try:
    # Zbyt wiele żądań lub przekroczony limit
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except RateLimitError as e:
    print(f"Code: {e.status_code}")  # 429
    print(f"Message: {e.message}")
    # Działanie: poczekaj i ponów próbę z wykładniczym opóźnieniem (exponential backoff)

500/503 — InternalServerError

Błędy 500 i 503 pochodzą od OpenAI, a nie od Ciebie. Twoje żądanie było poprawne; infrastruktura po prostu nie była w stanie go przetworzyć. Ponów próbę po krótkiej przerwie: w zdecydowanej większości przypadków druga lub trzecia próba kończy się sukcesem.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 lub 503
    print(f"Message: {e.message}")
    # Działanie: ponów próbę po opóźnieniu; błąd leży po stronie OpenAI

Kompleksowa obsługa błędów

Połączmy te zachowania w jednej funkcji. Logika polega na triażu: błędy krytyczne są zamieniane na RuntimeError i natychmiast podnoszone, błędy przejściowe uruchamiają oczekiwanie, które podwaja się z każdym obrotem, a jeśli budżet prób zostanie wyczerpany, wywołanie kończy się czystym niepowodzeniem, zamiast zwracać pustą wartość, którą wywołujący mógłby źle zinterpretować.

from openai import OpenAI, APIError, AuthenticationError, RateLimitError
from openai import BadRequestError, APIConnectionError, InternalServerError
import time

client = OpenAI()

def robust_api_call(prompt: str, model: str = "gpt-5.6-terra",
                    max_retries: int = 3) -> str:
    """Wywołanie API z kompleksową obsługą błędów."""

    for attempt in range(max_retries):
        try:
            response = client.responses.create(
                model=model,
                input=prompt
            )
            return response.output_text

        except AuthenticationError:
            # Nie powtarzaj — klucz jest nieprawidłowy
            raise RuntimeError("Nieprawidłowy klucz API. Sprawdź OPENAI_API_KEY.")

        except BadRequestError as e:
            # Nie powtarzaj — żądanie jest niepoprawne
            raise RuntimeError(f"Nieprawidłowe żądanie: {e.message}")

        except RateLimitError:
            # Ponów z wykładniczym opóźnieniem
            delay = 2 ** attempt
            print(f"Osiągnięto limit速率. Oczekiwanie {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Ponów — błąd po stronie serwera
            delay = 2 ** attempt
            print(f"Błąd serwera. Próba {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Ponów — problem z siecią
            delay = 2 ** attempt
            print(f"Błąd połączenia. Próba {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Niepowodzenie po {max_retries} próbach")

# Użycie
try:
    result = robust_api_call("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Błąd krytyczny: {e}")

Specyficzne błędy Responses API

Dwie sytuacje zasługują na osobne potraktowanie, ponieważ pojawiają się pod ogólnym kodem, ale wymagają bardzo specyficznego rozwiązania.

Zbyt długi kontekst

Monit (prompt), który przekracza okno kontekstowe, zwraca kod 400, tak samo jak literówka w parametrze. Aby rozróżnić te dwie sytuacje, sprawdź komunikat: obecność context_length_exceeded wskazuje na konieczność skrócenia tekstu lub przejścia na model z większym oknem kontekstowym, zamiast przeglądania swoich parametrów.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Przekracza okno kontekstowe
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Monit jest zbyt długi dla tego modelu.")
        print("Rozwiązania: skróć tekst lub przełącz się na model")
        print("z większym oknem kontekstowym.")

Model niedostępny

Identyfikatory modeli nie są wieczne. Wdrożenie, które nadal odwołuje się do wycofanego modelu, zakończy się niepowodzeniem z kodem 404, powodując awarię całej aplikacji, mimo że dzień wcześniej działała poprawnie. Obsłuż ten przypadek wyraźnie: to automatyczne przypomnienie o aktualizacji konfiguracji.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # wycofany z API 23 października 2026 r.
        input="Test"
    )
except NotFoundError as e:
    print(f"Nie znaleziono modelu: {e.message}")
    print("Użyj gpt-5.6-sol, zamiennika wskazanego przez OpenAI, lub nowszego modelu.")

Strukturalne logowanie błędów

Błąd, którego nie zalogowano, to błąd, o którym dowiesz się z zgłoszenia klienta. Logowanie w formacie JSON, a nie jako zwykły tekst, zmienia wszystko, gdy potrzebujesz agregacji: możesz liczyć błędy 429 na godzinę, filtrować po response_id lub śledzić dryf zużycia, co jest niemożliwe przy ręcznie pisanych liniach logów.

import logging
import json
from datetime import datetime

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("openai_client")

def call_with_log(prompt: str) -> str:
    """Wywołanie API ze strukturalnym logowaniem."""
    request_id = None

    try:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt
        )

        logger.info(json.dumps({
            "event": "api_success",
            "model": response.model,
            "tokens": response.usage.total_tokens,
            "response_id": response.id,
            "timestamp": datetime.now().isoformat()
        }))

        return response.output_text

    except APIError as e:
        logger.error(json.dumps({
            "event": "api_error",
            "status_code": e.status_code,
            "message": e.message,
            "timestamp": datetime.now().isoformat()
        }))
        raise

result = call_with_log("Hello!")

Tabela podsumowująca

Miej tę tabelę pod ręką: podsumowuje ona decyzję do podjęcia dla każdego kodu.

KodWyjątekPonowić?Działanie
400BadRequestErrorNiePopraw żądanie
401AuthenticationErrorNieZweryfikuj klucz API
403PermissionDeniedErrorNieZweryfikuj uprawnienia
404NotFoundErrorNieZweryfikuj model/endpoint
422UnprocessableEntityErrorNiePopraw format
429RateLimitErrorTakWykładnicze opóźnienie (exponential backoff)
500InternalServerErrorTakPoczekaj i ponów próbę
503InternalServerErrorTakUsługa tymczasowo niedostępna

Kluczowe wnioski

  • Kategoryzuj błędy: możliwe do ponowienia (429, 500, 503) vs krytyczne (400, 401, 403)
  • Używaj wykładniczego opóźnienia (exponential backoff) dla błędów możliwych do ponowienia
  • Nigdy nie powtarzaj prób przy błędach uwierzytelniania lub nieprawidłowych żądaniach
  • Loguj każdy błąd z kontekstem (kod, wiadomość, znacznik czasu)
  • SDK automatycznie obsługuje 2 ponowienia – skonfiguruj max_retries, jeśli jest taka potrzeba