Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Hibakezelés és HTTP-kódok

12. lecke 22 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Hibakezelés és HTTP-kódok
  2. OpenAI API HTTP-kódok
  3. Átfogó hibakezelő
  4. A Responses API specifikus hibái
  5. Strukturált hibanaplózás
  6. Összefoglaló táblázat
  7. Főbb megállapítások

Frissítve: 2026. november 3. az OpenAI dokumentációja alapján: a temperature és a top_p paraméterek csak none erő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 a reasoning={"effort": "none"} (Responses API) vagy reasoning_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-4o volt, amely 2027. január 14-ig még elérhető; a példa most a gpt-4-turbo modellt 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ódKivételÚjrapróbálkozás?Teendő
400BadRequestErrorNemJavítsd a kérést
401AuthenticationErrorNemEllenőrizd az API-kulcsot
403PermissionDeniedErrorNemEllenőrizd a jogosultságokat
404NotFoundErrorNemEllenőrizd a modellt/végpontot
422UnprocessableEntityErrorNemJavítsd a formátumot
429RateLimitErrorIgenExponenciális visszalépés
500InternalServerErrorIgenVárj, majd próbáld újra
503InternalServerErrorIgenSzolgá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