Zpracování chyb a HTTP kódy
Na této stránce
Aktualizováno 3. listopadu 2026 na základě dokumentace OpenAI: parametry
temperatureatop_pjsou přijímány pouze při úsilí o odvozování (reasoning effort) nastaveném nanone, zatímco modely GPT-5.6 ve výchozím nastavení odvozují (medium). Volání, která tyto parametry nastavují, musí proto specifikovatreasoning={"effort": "none"}(Responses API) neboreasoning_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ód | Výjimka | Opakovat? | Akce |
|---|---|---|---|
| 400 | BadRequestError | Ne | Oprav požadavek |
| 401 | AuthenticationError | Ne | Zkontroluj API klíč |
| 403 | PermissionDeniedError | Ne | Zkontroluj oprávnění |
| 404 | NotFoundError | Ne | Zkontroluj model/endpoint |
| 422 | UnprocessableEntityError | Ne | Oprav formát |
| 429 | RateLimitError | Ano | Exponenciální backoff |
| 500 | InternalServerError | Ano | Počkej a zkus znovu |
| 503 | InternalServerError | Ano | Služ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