Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Veahandlus ja HTTP-koodid

Õppetund 12 / 22 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Veahandlus ja HTTP-koodid
  2. OpenAI API HTTP-koodid
  3. Põhjalik veahaldur
  4. Responses API spetsiifilised vead
  5. Struktureeritud vealogimine
  6. Kokkuvõtlik tabel
  7. Peamised punktid

Uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid temperature ja top_p aktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) on määratud väärtusega none, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldama reasoning={"effort": "none"} (Responses API) või reasoning_effort="none" (Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.

Selgitatud 3. novembril 2026 OpenAI Deprecations lehe põhjal: eemaldatud mudeli näites kasutati varem gpt-4o, mis on kättesaadav kuni 14. jaanuarini 2027; nüüd kasutatakse gpt-4-turbo, mis lõpetati 23. oktoobril 2026 (asendajaks märgitud gpt-5.6-sol). Allikas: Deprecations.

Veahandlus ja HTTP-koodid

Tootmiskeskkonnas on vead paratamatud. Võrk katkeb, API võti aegub, kolleeg paigutab vigase parameetri või API ise kogeb kolmeminutilist seisakut. API tagastatavate HTTP-koodide mõistmine ja nende korrektne käsitlemine on hädavajalik töökindlate rakenduste loomisel. Kogu väljakutse taandub ühele küsimusele, mille pead iga erandi puhul endalt küsima: kas see kaob, kui proovin uuesti, või jään ma lõputult tsüklisse probleemi tõttu, mida saab lahendada ainult inimene?

OpenAI API HTTP-koodid

API tagastab iga päringu tulemuse näitamiseks standardseid HTTP-koode. Pythoni SDK ei võimalda neid koode käsitsi hallata; selle asemel teisendab see ühe neist tüübitud erandiks, mida saad eraldi püüda. See võimaldab kirjutada täpseid except plokke, mitte kasutada üldist except Exception, mis varjaks probleemi olemust.

from openai import OpenAI
from openai import (
    APIError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    APIConnectionError,
    InternalServerError,
    PermissionDeniedError,
    NotFoundError,
    UnprocessableEntityError,
)

client = OpenAI()

401 — AuthenticationError

401 tähendab, et API võti on vigane või puudub. Tavaliselt kohtad seda esimesel kasutuselevõtul, kui keskkonnamuutujat pole konteinerisse edastatud. Uuesti proovimine on kasutu: võti on sama vigane ka kümne sekundi pärast.

try:
    # Vigane või puuduv API võti
    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}")
    # Tegevus: kontrolli API võtit, vajadusel genereeri uus

400 — BadRequestError

401 annab märku, et päring on valesti vormistatud. Siin on temperatuuriks määratud 5.0, kuigi maksimaalne lubatud väärtus on 2.0. Veateade nimetab peaaegu alati vigast parameetrit, mistõttu on see kõige kiiremini lahendatav viga – eeldusel, et logid selle õigesti, mitte ei neela seda vaikselt.

try:
    # Vigased parameetrid
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature nõuab effort none
        input="Test",
        temperature=5.0  # Vigane väärtus (max 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Tegevus: paranda päringu parameetrid

429 — RateLimitError

429 tähendab, et saadad liiga palju päringuid või oled ületanud oma kvooti. Erinevalt kahest eelmisest on see viga oma olemuselt ajutine: loendur nullitakse. See on klassikaline juhtum uuesti proovimiseks, kuid selliseks, mis ootab – ja iga katsega järjest kauem.

try:
    # Liiga palju päringuid või kvoot ületatud
    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}")
    # Tegevus: oota ja proovi uuesti eksponentsiaalse tagasiminekuga

500/503 — InternalServerError

500 ja 503 vead tulevad OpenAI poolt, mitte sinu poolt. Sinu päring oli korrektne, kuid taristu lihtsalt ei suutnud seda töödelda. Proovi mõne viivituse järel uuesti: valdav enamikul juhtudel õnnestub teine või kolmas katse.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 või 503
    print(f"Message: {e.message}")
    # Tegevus: proovi viivitusega uuesti; viga on OpenAI poolel

Põhjalik veahaldur

Ühendame need käitumised ühte funktsiooni. Loogika on triaaž: fataalsed vead teisendatakse RuntimeError-iks ja visatakse koheselt, ajutised vead käivitavad oote, mis iga ringiga kahekordistub, ja kui katsete eelarve on ammendatud, ebaõnnestub väljakutse puhtalt, selle asemel et tagastada tühi väärtus, mida kutsuja võiks valesti tõlgendada.

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 väljakutse põhjaliku veahandlusega."""

    for attempt in range(max_retries):
        try:
            response = client.responses.create(
                model=model,
                input=prompt
            )
            return response.output_text

        except AuthenticationError:
            # Ära proovi uuesti — võti on vigane
            raise RuntimeError("Vigane API võti. Kontrolli OPENAI_API_KEY.")

        except BadRequestError as e:
            # Ära proovi uuesti — päring on valesti vormistatud
            raise RuntimeError(f"Vigane päring: {e.message}")

        except RateLimitError:
            # Proovi uuesti eksponentsiaalse tagasiminekuga
            delay = 2 ** attempt
            print(f"Piirmäär saavutatud. Ootan {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Proovi uuesti — serveripoolne viga
            delay = 2 ** attempt
            print(f"Serveri viga. Katse {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Proovi uuesti — võrguprobleem
            delay = 2 ** attempt
            print(f"Ühenduse viga. Katse {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Ebaõnnestus pärast {max_retries} katset")

# Kasutamine
try:
    result = robust_api_call("Tere!")
    print(result)
except RuntimeError as e:
    print(f"Fataalne viga: {e}")

Responses API spetsiifilised vead

Kaks olukorda väärivad eraldi käsitlemist, kuna need ilmuvad üldise koodi all, kuid nõuavad väga spetsiifilist lahendust.

Kontekst liiga pikk

Sisend, mis ületab kontekstiakna, tagastab 400, täpselt nagu trükiviga parameetris. Et neid kahte eristada, uurige teadet: context_length_exceeded olemasolu suunab sind teksti lühendama või suurema kontekstiaknaga mudelile üle minema, mitte oma parameetreid üle vaatama.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Ületab kontekstiakna
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Sisend on selle mudeli jaoks liiga pikk.")
        print("Lahendused: lühenda teksti või mine üle mudelile")
        print("suurema kontekstiaknaga.")

Mudel pole saadaval

Mudeli identifikaatorid pole igavesed. Kasutuselevõtt, mis viitab endiselt retireeritud mudelile, ebaõnnestub 404-ga, põhjustades kogu rakenduse kokkujooksmise, kuigi eelmisel päeval töötas see. Käitle seda juhtumit selgelt: see on automaatne meeldetuletus oma konfiguratsiooni uuendamiseks.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # eemaldatud API-st 23. oktoobril 2026
        input="Test"
    )
except NotFoundError as e:
    print(f"Mudelit ei leitud: {e.message}")
    print("Kasuta gpt-5.6-sol, OpenAI poolt märgitud asendajat, või uuemat mudelit.")

Struktureeritud vealogimine

Logimata viga on viga, millest saad teada kliendi pöördumise kaudu. Logimine JSON-formaadis vaba teksti asemel muudab kõike, kui vaja on agregeerimist: saad lugeda 429 veade arvu tunnis, filtreerida response_id järgi või jälgida tarbimise kõrvalekallet, mis on käsitsi kirjutatud logiridadega võimatu.

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 väljakutse struktureeritud logimisega."""
    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("Tere!")

Kokkuvõtlik tabel

Hoia see tabel käepärast: see võtab kokku otsuse, mida iga koodi puhul teha.

KoodErandProovi uuesti?Tegevus
400BadRequestErrorEiParanda päring
401AuthenticationErrorEiKontrolli API võtit
403PermissionDeniedErrorEiKontrolli õigusi
404NotFoundErrorEiKontrolli mudelit/lõpppunkti
422UnprocessableEntityErrorEiParanda formaati
429RateLimitErrorJahEksponentsiaalne tagasiminek
500InternalServerErrorJahOota ja proovi uuesti
503InternalServerErrorJahTeenus ajutiselt kättesaamatu

Peamised punktid

  • Liigita vead: korratavad (429, 500, 503) vs fataalsed (400, 401, 403)
  • Kasuta korratavate vigade puhul eksponentsiaalset tagasiminekut
  • Ära kunagi proovi uuesti autentimis- või vigase päringu vigade korral
  • Logi iga viga kontekstiga (kood, sõnum, ajatempel)
  • SDK haldab automaatselt 2 korduskatset – konfigureeri max_retries vajadusel