Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Rukovanje greškama i HTTP kodovi

Lekcija 12 od 22 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Rukovanje greškama i HTTP kodovi
  2. HTTP kodovi OpenAI API-ja
  3. Sveobuhvatni rukovatelj greškama
  4. Specifične greške Responses API-ja
  5. Strukturirano logiranje grešaka
  6. Sažetna tablica
  7. Ključne točke

Ažurirano 3. studenoga 2026. na temelju OpenAI dokumentacije: parametri temperature i top_p prihvaćeni su samo uz napor rezoniranja (reasoning effort) postavljen na none, dok modeli GPT-5.6 prema zadanim postavkama rezoniraju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificirati reasoning={"effort": "none"} (Responses API) ili reasoning_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 koristi gpt-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.

KodIznimkaPonoviti?Akcija
400BadRequestErrorNeIspravi zahtjev
401AuthenticationErrorNeProvjeri API ključ
403PermissionDeniedErrorNeProvjeri dopuštenja
404NotFoundErrorNeProvjeri model/krajnju točku
422UnprocessableEntityErrorNeIspravi format
429RateLimitErrorDaEksponencijalno odgađanje
500InternalServerErrorDaPričekaj i ponovi
503InternalServerErrorDaUsluga 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_retries ako je potrebno