Obsługa błędów i kody HTTP
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry
temperatureitop_psą akceptowane tylko przy wysiłku rozumowania (reasoning effort) ustawionym nanone, 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) lubreasoning_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żywagpt-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.
| Kod | Wyjątek | Ponowić? | Działanie |
|---|---|---|---|
| 400 | BadRequestError | Nie | Popraw żądanie |
| 401 | AuthenticationError | Nie | Zweryfikuj klucz API |
| 403 | PermissionDeniedError | Nie | Zweryfikuj uprawnienia |
| 404 | NotFoundError | Nie | Zweryfikuj model/endpoint |
| 422 | UnprocessableEntityError | Nie | Popraw format |
| 429 | RateLimitError | Tak | Wykładnicze opóźnienie (exponential backoff) |
| 500 | InternalServerError | Tak | Poczekaj i ponów próbę |
| 503 | InternalServerError | Tak | Usł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