Obvladovanje napak in kode HTTP
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra
temperatureintop_psta sprejeta le pri naporu razmišljanja (reasoning effort) vrednostinone, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določitireasoning={"effort": "none"}(Responses API) alireasoning_effort="none"(Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.
Pojasnjeno 3. novembra 2026 na podlagi strani Deprecations (Opustitve) podjetja OpenAI: odstranjeni primer modela je prej uporabljal
gpt-4o, ki je na voljo do 14. januarja 2027; zdaj uporabljagpt-4-turbo, ki je bil ukinjen 23. oktobra 2026 (navedena zamenjava:gpt-5.6-sol). Vir: Deprecations.
Obvladovanje napak in kode HTTP
V produkcijskem okolju so napake neizogibne. Omrežje odpove, ključ API poteče, sodelavec uvede neveljaven parameter ali pa sam API doživi triminutni izpad. Razumevanje kod HTTP, ki jih vrača API, in njihovo pravilno obravnavanje sta ključna za gradnjo robustnih aplikacij. Celoten izziv se свaja na eno vprašanje, ki si ga moraš zastaviti ob vsaki izjemi: bo ta težava izginila, če poskusim znova, ali pa bom neskončno krožil okoli problema, ki ga lahko reši le človek?
Kode HTTP API-ja OpenAI
API vrača standardne kode HTTP, ki označujejo rezultat vsake zahteve. Python SDK ti ne omogoča ročnega obravnavanja teh kod; namesto tega vsako kodo prevede v tipizirano izjemo, ki jo lahko ujameš ločeno. To ti omogoča pisanje natančnih blokov except namesto splošnega except Exception, ki bi zabrisal naravo težave.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Koda 401 pomeni, da je ključ API neveljaven ali manjka. To običajno opaziš ob prvi uvedbi, ko spremenljivka okolja ni bila posredovana v vsebnik. Ponovni poskus je brezpredmeten: ključ bo čez deset sekund prav tako neveljaven.
try:
# Neveljaven ali manjkajoč ključ 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}")
# Ukrep: preveri ključ API, po potrebi ga ponovno ustvari
400 — BadRequestError
Koda 400 ti sporoča, da je zahteva napačno oblikovana. Tukaj je na primer podana temperatura 5.0, medtem ko je največja sprejemljiva vrednost 2.0. Sporočilo o napaki skoraj vedno imenuje okvarjeni parameter, zaradi česar je to napako najhitreje odpraviti – pod pogojem, da jo pravilno zabeležiš v dnevnik, namesto da bi jo tiho pogoltnil.
try:
# Neveljavni parametri
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperatura zahteva effort none
input="Test",
temperature=5.0 # Neveljavna vrednost (največ 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Ukrep: popravi parametre zahteve
429 — RateLimitError
Koda 429 pomeni, da pošiljaš preveč zahtev ali si presegel svojo kvoto. Za razliko od prejšnjih dveh je ta napaka po naravi začasna: števec se ponastavi. To je učbeniški primer za ponovni poskus, vendar takšen, ki počaka – in z vsakim poskusom čaka dlje.
try:
# Preveč zahtev ali presežena kvota
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}")
# Ukrep: počakaj in poskusi znova z eksponentnim zamikom
500/503 — InternalServerError
Napaki 500 in 503 izvirata od OpenAI, ne od tebe. Tvoja zahteva je bila veljavna, infrastruktura pa je preprosto ni mogla obdelati. Poskusi znova po kratkem zamiku: v veliki večini primerov drugi ali tretji poskus uspe.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 ali 503
print(f"Message: {e.message}")
# Ukrep: poskusi znova po zamiku; napaka je na strani OpenAI
Celovit obravnavalec napak
Združimo ta vedenja v eno samo funkcijo. Logika je triaža: usodne napake se pretvorijo v RuntimeError in se takoj sprožijo, prehodne napake sprožijo čakanje, ki se z vsakim krogom podvoji, in če se proračun poskusov izčrpa, klic čisto odpove, namesto da bi vrnil prazno vrednost, ki bi jo klicatelj lahko napačno razumel.
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:
"""Klic API-ja s celovitim obvladovanjem napak."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Ne ponavljaj — ključ je neveljaven
raise RuntimeError("Neveljaven ključ API. Preveri OPENAI_API_KEY.")
except BadRequestError as e:
# Ne ponavljaj — zahteva je napačno oblikovana
raise RuntimeError(f"Neveljavna zahteva: {e.message}")
except RateLimitError:
# Ponovi z eksponentnim zamikom
delay = 2 ** attempt
print(f"Dosežena omejitev hitrosti. Čakanje {delay}s...")
time.sleep(delay)
except InternalServerError:
# Ponovi — napaka na strani strežnika
delay = 2 ** attempt
print(f"Napaka strežnika. Poskus {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Ponovi — težava z omrežjem
delay = 2 ** attempt
print(f"Napaka povezave. Poskus {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Neuspešno po {max_retries} poskusih")
# Uporaba
try:
result = robust_api_call("Hello!")
print(result)
except RuntimeError as e:
print(f"Usodna napaka: {e}")
Napake, specifične za Responses API
Dve situaciji zaslužita ločeno obravnavo, saj se pojavljata pod splošno kodo, vendar zahtevata zelo specifičen popravek.
Predolg kontekst
Poziv, ki preseže okno konteksta, vrne kodo 400, tako kot tipkarska napaka v parametru. Da bi razlikoval med obema, preglej sporočilo: prisotnost niza context_length_exceeded te usmeri k obrezovanju besedila ali preklopu na model z večjim oknom konteksta, namesto da bi pregledoval svoje parametre.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Presega okno konteksta
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("Poziv je predolg za ta model.")
print("Rešitve: obreži besedilo ali preklopi na model")
print("z večjim oknom konteksta.")
Model ni na voljo
Identifikatorji modelov niso večni. Uvedba, ki še vedno sklicuje na upokojen model, odpove s kodo 404, kar povzroči padec celotne aplikacije, čeprav je dan prej delovala. Ta primer obravnavaj izrecno: samodejni opomnik je, da posodobiš svojo konfiguracijo.
try:
response = client.responses.create(
model="gpt-4-turbo", # umaknjen iz API-ja 23. oktobra 2026
input="Test"
)
except NotFoundError as e:
print(f"Model ni najden: {e.message}")
print("Uporabi gpt-5.6-sol, zamenjavo, ki jo navaja OpenAI, ali novejši model.")
Strukturirano beleženje napak v dnevnik
Napaka, ki ni zabeležena v dnevnik, je napaka, za katero boš izvedel prek prijave stranke. Beleženje v formatu JSON namesto v prosto besedilo spremeni vse, ko potrebuješ agregacijo: lahko šteješ kode 429 na uro, filtriraš po response_id ali slediš driftu porabe, kar pri ročno napisanih vrsticah dnevnika ni mogoče.
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:
"""Klic API-ja s strukturiranim beleženjem v dnevnik."""
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!")
Povzetna tabela
Imej to mrežo pri roki: povzema odločitev za vsako kodo.
| Koda | Izjema | Ponovi? | Ukrep |
|---|---|---|---|
| 400 | BadRequestError | Ne | Popravi zahtevo |
| 401 | AuthenticationError | Ne | Preveri ključ API |
| 403 | PermissionDeniedError | Ne | Preveri dovoljenja |
| 404 | NotFoundError | Ne | Preveri model/končno točko |
| 422 | UnprocessableEntityError | Ne | Popravi format |
| 429 | RateLimitError | Da | Eksponentni zamik |
| 500 | InternalServerError | Da | Počakaj in poskusi znova |
| 503 | InternalServerError | Da | Storitev začasno ni na voljo |
Ključne ugotovitve
- Razvrsti napake: ponovljive (429, 500, 503) proti usodnim (400, 401, 403)
- Za ponovljive napake uporabi eksponentni zamik
- Nikoli ne ponavljaj pri napakah avtentikacije ali neveljavnih zahtevah
- Vsako napako zabeleži v dnevnik s kontekstom (koda, sporočilo, časovni žig)
- SDK samodejno obdela 2 ponovna poskusa – po potrebi konfiguriraj
max_retries