Hibakezelés és HTTP-kódok
Ezen az oldalon
Frissítve: 2026. november 3. az OpenAI dokumentációja alapján: a
temperatureés atop_pparaméterek csaknoneerősségű gondolkodási mód (reasoning effort) esetén fogadhatók el, míg a GPT-5.6 modellek alapértelmezetten (medium) gondolkodnak. Ezért az ezeket a paramétereket beállító hívásoknál meg kell adni areasoning={"effort": "none"}(Responses API) vagyreasoning_effort="none"(Chat Completions) beállítást. Források: GPT-6 használata · GPT-5.6 Terra.
Tisztázva: 2026. november 3. az OpenAI Elavult funkciók (Deprecations) oldala alapján: a korábban használt eltávolított modellpélda a
gpt-4ovolt, amely 2027. január 14-ig még elérhető; a példa most agpt-4-turbomodellt használja, amelyet 2026. október 23-án megszüntettek (a javasolt helyettesítő:gpt-5.6-sol). Forrás: Elavult funkciók.
Hibakezelés és HTTP-kódok
Éles környezetben a hibák elkerülhetetlenek. Leszakad a hálózat, lejár egy API-kulcs, egy kolléga érvénytelen paramétert deployol, vagy maga az API három perces kimaradást szenved. Az alkalmazások robusztussá tételéhez elengedhetetlen, hogy értsd az API által visszaadott HTTP-kódokat, és helyesen kezeld őket. A teljes kihívás egyetlen kérdésre vezethető vissza, amit minden kivétel esetén fel kell tenned: eltűnik ez a hiba, ha újrapróbálom, vagy végtelen ciklusba kergetem magam egy olyan problémával, amit csak ember tud megoldani?
OpenAI API HTTP-kódok
Az API szabványos HTTP-kódokat ad vissza az egyes kérések eredményének jelzésére. A Python SDK nem engedi, hogy ezeket a kódokat manuálisan kezeld; ehelyett minden kódot egy típusos kivétellé alakít át, amelyet külön-külön elkapdhatsz. Ez lehetővé teszi, hogy precíz except blokkokat írj, ahelyett, hogy egy mindent elnyelő except Exception blokkot használnál, ami elmosná a probléma valódi természetét.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
A 401-es kód azt jelzi, hogy az API-kulcs érvénytelen vagy hiányzik. Ezt általában az első telepítés során látod, amikor a környezeti változót nem propagáltad a konténer felé. Az újrapróbálkozás haszontalan: tíz másodperc múlva a kulcs ugyanolyan érvénytelen lesz.
try:
# Érvénytelen vagy hiányzó API-kulcs
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}")
# Teendő: ellenőrizd az API-kulcsot, szükség esetén generáld újra
400 — BadRequestError
A 400-as kód azt jelzi, hogy a kérés rosszul van felépítve. Itt például egy 5.0 értékű hőmérsékletet (temperature) adtunk meg, miközben a maximálisan elfogadott érték 2.0. A hibaüzenet szinte mindig megnevezi a hibás paramétert, így ez a leggyorsabban javítható hiba – feltéve, hogy helyesen naplózod, és nem nyelődik el csendben.
try:
# Érvénytelen paraméterek
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # a temperature paraméterhez 'none' erősség szükséges
input="Test",
temperature=5.0 # Érvénytelen érték (max 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Teendő: javítsd a kérés paramétereit
429 — RateLimitError
A 429-es kód azt jelzi, hogy túl sok kérést küldesz, vagy túllépted a kvótádat. Az előző kettővel ellentétben ez a hiba természeténél fogva átmeneti: a számláló visszaáll. Ez a tankönyvi példa az újrapróbálkozásra, de olyanra, amely várakozik – és minden egyes próbálkozással egyre hosszabb ideig vár.
try:
# Túl sok kérés vagy kvóta túllépése
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}")
# Teendő: várj, majd próbáld újra exponenciális visszalépéssel (exponential backoff)
500/503 — InternalServerError
Az 500-as és 503-as hibák az OpenAI oldalán keletkeznek, nem nálad. A kérésed érvényes volt; az infrastruktúra egyszerűen nem tudta feldolgozni. Próbáld meg később, egy rövid várakozás után: az esetek túlnyomó többségében a második vagy harmadik próbálkozás sikerrel jár.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 vagy 503
print(f"Message: {e.message}")
# Teendő: várj, majd próbáld újra; a hiba az OpenAI oldalán van
Átfogó hibakezelő
Foglaljuk össze ezeket a viselkedéseket egyetlen függvényben. A logika egyfajta triázs: a végzetes hibákat RuntimeError-ré alakítjuk és azonnal dobjuk, az átmeneti hibák esetén várakozást iktatunk be, amely minden körben megduplázódik, és ha a próbálkozások kerete kimerül, a hívás tisztán meghiúsul, ahelyett, hogy üres értéket adna vissza, amit a hívó fél félreérthetne.
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:
"""API hívás átfogó hibakezeléssel."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Ne próbáld újra – a kulcs érvénytelen
raise RuntimeError("Érvénytelen API-kulcs. Ellenőrizd az OPENAI_API_KEY változót.")
except BadRequestError as e:
# Ne próbáld újra – a kérés rosszul van felépítve
raise RuntimeError(f"Érvénytelen kérés: {e.message}")
except RateLimitError:
# Újrapróbálkozás exponenciális visszalépéssel
delay = 2 ** attempt
print(f"Sebességkorlát elérve. Várakozás {delay}s...")
time.sleep(delay)
except InternalServerError:
# Újrapróbálkozás – szerveroldali hiba
delay = 2 ** attempt
print(f"Szerverhiba. Próbálkozás: {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Újrapróbálkozás – hálózati probléma
delay = 2 ** attempt
print(f"Kapcsolati hiba. Próbálkozás: {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Sikertelen {max_retries} próbálkozás után")
# Használat
try:
result = robust_api_call("Hello!")
print(result)
except RuntimeError as e:
print(f"Végzetes hiba: {e}")
A Responses API specifikus hibái
Két helyzet külön kezelést érdemel, mert bár általános kód alatt jelennek meg, nagyon specifikus javítást igényelnek.
Túl hosszú kontextus
Ha egy prompt meghaladja a kontextusablak méretét, az API 400-as kódot ad vissza, akárcsak egy elgépelés esetén. A kettő megkülönböztetéséhez vizsgáld meg az üzenetet: a context_length_exceeded kifejezés jelenléte arra utal, hogy a szöveget le kell vágnod, vagy nagyobb kontextusablakkal rendelkező modellre kell váltanod, nem pedig a paramétereidet kell átnézned.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Meghaladja a kontextusablakot
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("A prompt túl hosszú ehhez a modellhez.")
print("Megoldások: vágd le a szöveget, vagy válts nagyobb")
print("kontextusablakkal rendelkező modellre.")
Modell nem elérhető
A modellazonosítók nem örökéletűek. Egy olyan telepítés, amely még egy visszavont modellre hivatkozik, 404-es hibával meghiúsul, ami az egész alkalmazás összeomlását okozhatja, pedig előző nap még működött. Kezeld ezt az esetet explicit módon: ez egy automatikus emlékeztető a konfiguráció frissítésére.
try:
response = client.responses.create(
model="gpt-4-turbo", # az API-ból 2026. október 23-án visszavonva
input="Test"
)
except NotFoundError as e:
print(f"A modell nem található: {e.message}")
print("Használd a gpt-5.6-sol modellt, amelyet az OpenAI helyettesítőként jelölt meg, vagy egy újabb modellt.")
Strukturált hibanaplózás
Egy naplózott hiba olyan hiba, amit csak egy ügyfélticketen keresztül fogsz felfedezni. Ha szabad szöveg helyett JSON-ban naplózol, az mindent megváltoztat, amikor aggregálnod kell az adatokat: megszámolhatod az óránkénti 429-es hibákat, szűrhetsz response_id szerint, vagy követheted a fogyasztás ingadozását, ami kézzel írt naplósorokkal lehetetlen.
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:
"""API hívás strukturált naplózással."""
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!")
Összefoglaló táblázat
Tartsd kéznél ezt a rácsot: összefoglalja, milyen döntést kell hoznod az egyes kódok esetén.
| Kód | Kivétel | Újrapróbálkozás? | Teendő |
|---|---|---|---|
| 400 | BadRequestError | Nem | Javítsd a kérést |
| 401 | AuthenticationError | Nem | Ellenőrizd az API-kulcsot |
| 403 | PermissionDeniedError | Nem | Ellenőrizd a jogosultságokat |
| 404 | NotFoundError | Nem | Ellenőrizd a modellt/végpontot |
| 422 | UnprocessableEntityError | Nem | Javítsd a formátumot |
| 429 | RateLimitError | Igen | Exponenciális visszalépés |
| 500 | InternalServerError | Igen | Várj, majd próbáld újra |
| 503 | InternalServerError | Igen | Szolgáltatás átmenetileg nem elérhető |
Főbb megállapítások
- Kategorizáld a hibákat: újrapróbálható (429, 500, 503) vs végzetes (400, 401, 403)
- Használj exponenciális visszalépést az újrapróbálható hibáknál
- Soha ne próbáld újra a hitelesítési vagy érvénytelen kérésből adódó hibákat
- Naplózz minden hibát kontextussal (kód, üzenet, időbélyeg)
- Az SDK automatikusan kezel 2 újrapróbálkozást – állítsd be a
max_retriesértéket, ha szükséges