Rukovanje greškama i HTTP kodovi
Na ovoj stranici
Ažurirano 3. studenoga 2026. na temelju OpenAI dokumentacije: parametri
temperatureitop_pprihvaćeni su samo uz napor rezoniranja (reasoning effort) postavljen nanone, dok modeli GPT-5.6 prema zadanim postavkama rezoniraju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificiratireasoning={"effort": "none"}(Responses API) ilireasoning_effort="none"(Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.
Pojanjeno 3. studenoga 2026. na temelju OpenAI stranice Deprecations: primjer uklonjenog modela prethodno je koristio
gpt-4o, koji je dostupan do 14. siječnja 2027.; sada koristigpt-4-turbo, koji je ukinut 23. listopada 2026. (naznačena zamjena:gpt-5.6-sol). Izvor: Deprecations.
Rukovanje greškama i HTTP kodovi
U produkcijskom okruženju greške su neizbježne. Mreža zakaže, API ključ istekne, kolega deploya neispravan parametar ili sam API doživi trominutni zastoj. Razumijevanje HTTP kodova koje API vraća i ispravno rukovanje njima ključno je za izgradnju pouzdanih aplikacija. Cijeli izazov svodi se na jedno pitanje koje si moraš postaviti za svaku iznimku: hoće li ovo nestati ako pokušam ponovno, ili ću beskonačno vrtjeti u krug oko problema koji može riješiti samo čovjek?
HTTP kodovi OpenAI API-ja
API vraća standardne HTTP kodove kako bi indicirao rezultat svakog zahtjeva. Python SDK ti ne dopušta ručno rukovanje ovim kodovima; umjesto toga, svaki od njih prevodi u tipiziranu iznimku koju možeš posebno uhvatiti. To ti omogućuje pisanje preciznih blokova except, a ne općenitog except Exception koji bi zamaglio prirodu problema.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Kod 401 označava da je API ključ neispravan ili nedostaje. Ovo obično vidiš tijekom prvog deploya kada varijabla okruženja nije proslijeđena u kontejner. Ponovni pokušaj je beskoristan: ključ će biti jednako neispravan i za deset sekundi.
try:
# Neispravan ili nedostajući API ključ
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}")
# Akcija: provjeri API ključ, regeneriraj ga ako je potrebno
400 — BadRequestError
Kod 400 govori ti da je zahtjev neispravno formiran. Ovdje je navedena temperatura od 5.0 kada je maksimalna prihvaćena vrijednost 2.0. Poruka o grešci gotovo uvijek imenuje neispravan parametar, što ovu grešku čini najbržom za popravak – pod uvjetom da je ispravno logiraš, a ne da je tiho progutaš.
try:
# Neispravni parametri
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature zahtijeva effort none
input="Test",
temperature=5.0 # Neispravna vrijednost (max 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Akcija: ispravi parametre zahtjeva
429 — RateLimitError
Kod 429 označava da šalješ previše zahtjeva ili si premašio svoju kvotu. Za razliku od prethodne dvije, ova greška je po prirodi privremena: brojač se resetira. Ovo je školski primjer za ponovni pokušaj, ali onaj koji čeka – i čeka sve dulje sa svakim pokušajem.
try:
# Previše zahtjeva ili premaš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}")
# Akcija: pričekaj i pokušaj ponovno s eksponencijalnim odgađanjem
500/503 — InternalServerError
Greške 500 i 503 dolaze od OpenAI-ja, a ne od tebe. Tvoj je zahtjev bio valjan; infrastruktura ga jednostavno nije mogla obraditi. Pokušaj ponovno nakon kašnjenja: u velikoj većini slučajeva, drugi ili treći pokušaj uspijeva.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 ili 503
print(f"Message: {e.message}")
# Akcija: pokušaj ponovno nakon kašnjenja; greška je na strani OpenAI-ja
Sveobuhvatni rukovatelj greškama
Spojimo ova ponašanja u jednu funkciju. Logika je trijaža: fatalne greške pretvaraju se u RuntimeError i odmah se podižu, prolazne greške pokreću čekanje koje se udvostručuje svakim krugom, a ako se potroši budžet pokušaja, poziv čisto faila umjesto da vraća praznu vrijednost koju pozivatelj može pogrešno protumačiti.
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 poziv sa sveobuhvatnim rukovanjem greškama."""
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 neispravan
raise RuntimeError("Neispravan API ključ. Provjeri OPENAI_API_KEY.")
except BadRequestError as e:
# Ne ponavljaj — zahtjev je neispravno formiran
raise RuntimeError(f"Neispravan zahtjev: {e.message}")
except RateLimitError:
# Ponovi s eksponencijalnim odgađanjem
delay = 2 ** attempt
print(f"Dosegnuto ograničenje stope. Čekam {delay}s...")
time.sleep(delay)
except InternalServerError:
# Ponovi — greška na strani poslužitelja
delay = 2 ** attempt
print(f"Greška poslužitelja. Pokušaj {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Ponovi — mrežni problem
delay = 2 ** attempt
print(f"Greška veze. Pokušaj {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Neuspjelo nakon {max_retries} pokušaja")
# Upotreba
try:
result = robust_api_call("Hello!")
print(result)
except RuntimeError as e:
print(f"Fatalna greška: {e}")
Specifične greške Responses API-ja
Dvije situacije zaslužuju zaseban tretman jer se pojavljuju pod generičkim kodom, ali zahtijevaju vrlo specifičan popravak.
Kontekst predugačak
Upit koji premašuje prozor konteksta vraća 400, baš kao i tipfeler u parametru. Da bi razlikovao ove dvije situacije, pregledaj poruku: prisutnost context_length_exceeded upućuje te prema skraćivanju teksta ili prelasku na model s većim prozorom konteksta, umjesto pregledavanja tvojih parametara.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Premašuje prozor konteksta
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("Upit je predugačak za ovaj model.")
print("Rješenja: skrati tekst ili prijeđi na model")
print("s većim prozorom konteksta.")
Model nedostupan
Identifikatori modela nisu vječni. Deploy koji još uvijek referencira umirovljeni model faila s 404, uzrokujući rušenje cijele aplikacije iako je dan prije radila. Obradi ovaj slučaj eksplicitno: to je automatski podsjetnik da ažuriraš svoju konfiguraciju.
try:
response = client.responses.create(
model="gpt-4-turbo", # umirovljen iz API-ja 23. listopada 2026.
input="Test"
)
except NotFoundError as e:
print(f"Model nije pronađen: {e.message}")
print("Koristi gpt-5.6-sol, zamjenu koju je naznačio OpenAI, ili noviji model.")
Strukturirano logiranje grešaka
Nelogirana greška je greška koju ćeš otkriti putem korisničkog ticketa. Logiranje u JSON formatu umjesto slobodnog teksta mijenja sve kada trebaš agregirati podatke: možeš brojati 429-e po satu, filtrirati po response_id ili pratiti drift potrošnje, što je nemoguće s ručno pisanim redovima loga.
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 poziv sa strukturiranim logiranjem."""
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!")
Sažetna tablica
Drži ovu mrežu pri ruci: sažima odluku koju trebaš donijeti za svaki kod.
| Kod | Iznimka | Ponoviti? | Akcija |
|---|---|---|---|
| 400 | BadRequestError | Ne | Ispravi zahtjev |
| 401 | AuthenticationError | Ne | Provjeri API ključ |
| 403 | PermissionDeniedError | Ne | Provjeri dopuštenja |
| 404 | NotFoundError | Ne | Provjeri model/krajnju točku |
| 422 | UnprocessableEntityError | Ne | Ispravi format |
| 429 | RateLimitError | Da | Eksponencijalno odgađanje |
| 500 | InternalServerError | Da | Pričekaj i ponovi |
| 503 | InternalServerError | Da | Usluga privremeno nedostupna |
Ključne točke
- Kategoriziraj greške: ponovljive (429, 500, 503) nasuprot fatalnim (400, 401, 403)
- Koristi eksponencijalno odgađanje za ponovljive greške
- Nikada ne ponavljaj autentifikacijske greške ili greške neispravnog zahtjeva
- Logiraj svaku grešku s kontekstom (kod, poruka, vremenska oznaka)
- SDK automatski obrađuje 2 ponovna pokušaja – konfiguriraj
max_retriesako je potrebno