Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Zpracování chyb a HTTP kódy

Lekce 12 z 22 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Zpracování chyb a HTTP kódy
  2. HTTP kódy API OpenAI
  3. Komplexní obsluha chyb
  4. Specifické chyby Responses API
  5. Strukturované logování chyb
  6. Souhrnná tabulka
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě dokumentace OpenAI: parametry temperature a top_p jsou přijímány pouze při úsilí o odvozování (reasoning effort) nastaveném na none, zatímco modely GPT-5.6 ve výchozím nastavení odvozují (medium). Volání, která tyto parametry nastavují, musí proto specifikovat reasoning={"effort": "none"} (Responses API) nebo reasoning_effort="none" (Chat Completions). Zdroje: Using GPT-6 · GPT-5.6 Terra.

Upřesněno 3. listopadu 2026 na základě stránky Deprecations od OpenAI: dříve použitý příklad odstraněného modelu využíval gpt-4o, který je dostupný až do 14. ledna 2027; nyní používá gpt-4-turbo, který byl ukončen 23. října 2026 (označená náhrada: gpt-5.6-sol). Zdroj: Deprecations.

Zpracování chyb a HTTP kódy

V produkčním prostředí jsou chyby nevyhnutelné. Síť vypadne, API klíč vyprší, kolega nasadí neplatný parametr nebo samotné API zaznamená tříminutový výpadek. Porozumění HTTP kódům, které API vrací, a jejich správné zpracování je zásadní pro budování robustních aplikací. Celá výzva se svádí na jednu otázku, kterou si musíš položit u každé výjimky: zmizí tento problém při opakovaném pokusu, nebo budu donekonečna cyklit na problému, který může vyřešit pouze člověk?

HTTP kódy API OpenAI

API vrací standardní HTTP kódy, které indikují výsledek každého požadavku. Python SDK ti neumožňuje zpracovávat tyto kódy ručně; místo toho každý z nich převádí na typovanou výjimku, kterou můžeš zachytit samostatně. To ti umožňuje psát přesné bloky except namísto univerzálního except Exception, který by zastřel podstatu problému.

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

client = OpenAI()

401 — AuthenticationError

Kód 401 signalizuje, že API klíč je neplatný nebo chybí. Obvykle se s tím setkáš při prvním nasazení, kdy se proměnná prostředí nepropagovala do kontejneru. Opakování je zbytečné: za deset sekund bude klíč stejně neplatný.

try:
    # Neplatný nebo chybějící API klíč
    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}")
    # Akce: ověř API klíč, v případě potřeby jej znovu vygeneruj

400 — BadRequestError

Kód 400 ti říká, že požadavek je chybně vytvořen. Zde je například poskytnuta hodnota temperature 5.0, zatímco maximální přijatelná hodnota je 2.0. Chybová zpráva téměř vždy pojmenuje vadný parametr, což z této chyby dělá tu nejrychleji opravitelnou – za předpokladu, že ji správně zaloguješ, místo abys ji tiše spolkl.

try:
    # Neplatné parametry
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature vyžaduje effort none
        input="Test",
        temperature=5.0  # Neplatná hodnota (max 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Akce: oprav parametry požadavku

429 — RateLimitError

Kód 429 indikuje, že odesíláš příliš mnoho požadavků nebo jsi překročil svou kvótu. Na rozdíl od předchozích dvou je tato chyba svou povahou dočasná: čítač se resetuje. Toto je učebnicový případ pro opakování, ale opakování, které čeká – a s každým pokusem čeká déle.

try:
    # Příliš mnoho požadavků nebo překročená kvóta
    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}")
    # Akce: počkej a zkus to znovu s exponenciálním backoffem

500/503 — InternalServerError

Chyby 500 a 503 pocházejí od OpenAI, ne od tebe. Tvůj požadavek byl platný; infrastruktura jej pouze nedokázala zpracovat. Zkus to znovu po prodlevě: ve velké většině případů druhý nebo třetí pokus uspěje.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 nebo 503
    print(f"Message: {e.message}")
    # Akce: zkus to znovu po prodlevě; chyba je na straně OpenAI

Komplexní obsluha chyb

Spojme si tato chování do jedné funkce. Logika je triáž: fatální chyby se převedou na RuntimeError a jsou okamžitě vyvolány, přechodné chyby spustí čekání, které se s každým kolem zdvojnásobí, a pokud se vyčerpá rozpočet pokusů, volání čistě selže, místo aby vracelo prázdnou hodnotu, kterou by volající mohl špatně interpretovat.

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:
    """Volání API s komplexním zpracováním chyb."""

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

        except AuthenticationError:
            # Neopakovat — klíč je neplatný
            raise RuntimeError("Neplatný API klíč. Zkontroluj OPENAI_API_KEY.")

        except BadRequestError as e:
            # Neopakovat — požadavek je chybně vytvořen
            raise RuntimeError(f"Neplatný požadavek: {e.message}")

        except RateLimitError:
            # Opakovat s exponenciálním backoffem
            delay = 2 ** attempt
            print(f"Dosažen limit rychlosti. Čekám {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Opakovat — chyba na straně serveru
            delay = 2 ** attempt
            print(f"Chyba serveru. Pokus {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Opakovat — problém se sítí
            delay = 2 ** attempt
            print(f"Chyba připojení. Pokus {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Selhání po {max_retries} pokusech")

# Použití
try:
    result = robust_api_call("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Fatální chyba: {e}")

Specifické chyby Responses API

Dvě situace si zaslouží samostatné zacházení, protože se objevují pod obecným kódem, ale vyžadují velmi specifickou opravu.

Kontext je příliš dlouhý

Prompt, který překročí kontextové okno, vrátí kód 400, stejně jako překlep v parametru. Aby sis je rozlišil, zkontroluj zprávu: přítomnost context_length_exceeded tě nasměruje ke zkrácení textu nebo přepnutí na model s větším kontextovým oknem, místo abys revidoval své parametry.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Překračuje kontextové okno
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Prompt je pro tento model příliš dlouhý.")
        print("Řešení: zkrať text nebo přepni na model")
        print("s větším kontextovým oknem.")

Model není dostupný

Identifikátory modelů nejsou věčné. Nasazení, které stále odkazuje na vyřazený model, selže s kódem 404, což způsobí pád celé aplikace, i když den předtím fungovala. Tento případ ošetři explicitně: je to automatická připomínka aktualizovat konfiguraci.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # vyřazeno z API 23. října 2026
        input="Test"
    )
except NotFoundError as e:
    print(f"Model nenalezen: {e.message}")
    print("Použij gpt-5.6-sol, náhradu označenou OpenAI, nebo novější model.")

Strukturované logování chyb

Chyba, která není zalogována, je chyba, kterou objevíš až prostřednictvím ticketu od zákazníka. Logování v JSON místo volného textu mění vše, když potřebuješ agregovat data: můžeš počítat chyby 429 za hodinu, filtrovat podle response_id nebo sledovat drift spotřeby, což je u ručně psaných řádků logů nemožné.

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:
    """Volání API se strukturovaným logováním."""
    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!")

Souhrnná tabulka

Měj tuto mřížku po ruce: shrnuje rozhodnutí, které musíš učinit pro každý kód.

KódVýjimkaOpakovat?Akce
400BadRequestErrorNeOprav požadavek
401AuthenticationErrorNeZkontroluj API klíč
403PermissionDeniedErrorNeZkontroluj oprávnění
404NotFoundErrorNeZkontroluj model/endpoint
422UnprocessableEntityErrorNeOprav formát
429RateLimitErrorAnoExponenciální backoff
500InternalServerErrorAnoPočkej a zkus znovu
503InternalServerErrorAnoSlužba je dočasně nedostupná

Klíčové poznatky

  • Kategorizuj chyby: opakovatelné (429, 500, 503) vs fatální (400, 401, 403)
  • Pro opakovatelné chyby použij exponenciální backoff
  • Nikdy neopakuj chyby autentizace nebo neplatného požadavku
  • Loguj každou chybu s kontextem (kód, zpráva, časové razítko)
  • SDK automaticky zpracovává 2 opakování – v případě potřeby nakonfiguruj max_retries