Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Obvladovanje napak in kode HTTP

Lekcija 12 od 22 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Obvladovanje napak in kode HTTP
  2. Kode HTTP API-ja OpenAI
  3. Celovit obravnavalec napak
  4. Napake, specifične za Responses API
  5. Strukturirano beleženje napak v dnevnik
  6. Povzetna tabela
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra temperature in top_p sta sprejeta le pri naporu razmišljanja (reasoning effort) vrednosti none, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določiti reasoning={"effort": "none"} (Responses API) ali reasoning_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 uporablja gpt-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.

KodaIzjemaPonovi?Ukrep
400BadRequestErrorNePopravi zahtevo
401AuthenticationErrorNePreveri ključ API
403PermissionDeniedErrorNePreveri dovoljenja
404NotFoundErrorNePreveri model/končno točko
422UnprocessableEntityErrorNePopravi format
429RateLimitErrorDaEksponentni zamik
500InternalServerErrorDaPočakaj in poskusi znova
503InternalServerErrorDaStoritev 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