Veahandlus ja HTTP-koodid
Sellel lehel
Uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid
temperaturejatop_paktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) on määratud väärtuseganone, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldamareasoning={"effort": "none"}(Responses API) võireasoning_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 kasutataksegpt-4-turbo, mis lõpetati 23. oktoobril 2026 (asendajaks märgitudgpt-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.
| Kood | Erand | Proovi uuesti? | Tegevus |
|---|---|---|---|
| 400 | BadRequestError | Ei | Paranda päring |
| 401 | AuthenticationError | Ei | Kontrolli API võtit |
| 403 | PermissionDeniedError | Ei | Kontrolli õigusi |
| 404 | NotFoundError | Ei | Kontrolli mudelit/lõpppunkti |
| 422 | UnprocessableEntityError | Ei | Paranda formaati |
| 429 | RateLimitError | Jah | Eksponentsiaalne tagasiminek |
| 500 | InternalServerError | Jah | Oota ja proovi uuesti |
| 503 | InternalServerError | Jah | Teenus 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_retriesvajadusel