Gydymas klaidomis ir HTTP kodai
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d. pagal „OpenAI“ dokumentaciją:
temperatureirtop_ppriimami tik esantnonelygio samprotavimui, tuo tarpu GPT-5.6 modeliai pagal numatytuosius nustatymus samprotauja (medium). Todėl kvietimuose, kuriuose nustatomi šie parametrai, būtina nurodytireasoning={"effort": "none"}(Responses API) arbareasoning_effort="none"(Chat Completions). Šaltiniai: Using GPT-6 · GPT-5.6 Terra.
Patikslinta 2026 m. lapkričio 3 d. pagal „OpenAI“ puslapį Deprecations: anksčiau naudotame pašalinto modelio pavyzdyje buvo
gpt-4o, kuris bus prieinamas iki 2027 m. sausio 14 d.; dabar naudojamasgpt-4-turbo, kuris buvo nutrauktas 2026 m. spalio 23 d. (nurodytas pakaitalas:gpt-5.6-sol). Šaltinis: Deprecations.
Gydymas klaidomis ir HTTP kodai
Gamyboje klaidos neišvengiamos. Nutraukiamas tinklo ryšys, baigiasi API rakto galiojimas, kolega įdiegia neteisingą parametrą arba pati API patiria trijų minučių sutrikimą. Suprasti API grąžinamus HTTP kodus ir teisingai juos apdoroti yra būtina norint kurti patikimas programas. Visa problema sukasi apie vieną klausimą, kurį turi sau užduoti dėl kiekvienos išimties: ar tai išnyks, jei bandysiu iš naujo, ar be galo sukiosi rate dėl problemos, kurią gali išspręsti tik žmogus?
„OpenAI“ API HTTP kodai
API grąžina standartinius HTTP kodus, nurodančius kiekvieno užklausos rezultatą. „Python“ SDK neleidžia šių kodų apdoroti rankiniu būdu; vietoj to jis kiekvieną kodą paverčia tipizuota išimtimi, kurią gali sugauti atskirai. Tai leidžia rašyti tikslius except blokus, o ne bendrą except Exception, kuris užgožtų problemos pobūdį.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
401 kodas rodo, kad API raktas yra neteisingas arba jo trūksta. Tai dažniausiai pasitaiko pirmojo diegimo metu, kai aplinkos kintamasis nebuvo perduotas konteineriui. Bandymas kartoti yra beprasmis: po dešimties sekundžių raktas bus toks pat neteisingas.
try:
# Netinkamas arba trūkstamas API raktas
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}")
# Veiksmas: patikrink API raktą, prireikus sugeneruok iš naujo
400 — BadRequestError
400 kodas signalizuoja, kad užklausa suformuota neteisingai. Čia pateikiama 5,0 temperatūros reikšmė, nors didžiausia leistina reikšmė yra 2,0. Klaidos pranešime beveik visada įvardijamas klaidingas parametras, todėl tai yra greičiausiai ištaisoma klaida – jei tik ją tinkamai užfiksuoji, o ne nutyli.
try:
# Netinkami parametrai
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature reikalauja effort none
input="Test",
temperature=5.0 # Netinkama reikšmė (maks. 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Veiksmas: ištaisyk užklausos parametrus
429 — RateLimitError
429 kodas rodo, kad siunčiama per daug užklausų arba viršyta tavo kvota. Skirtingai nei ankstesniais dviem atvejais, ši klaida yra laikino pobūdžio: skaitiklis iš naujo nustatomas. Tai klasikinis atvejis bandymui kartoti, tačiau tokiam, kuris laukia – ir kiekvieną kartą laukia vis ilgiau.
try:
# Per daug užklausų arba viršyta 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}")
# Veiksmas: palauk ir bandyk iš naujo taikydamas eksponentinį delsą
500/503 — InternalServerError
500 ir 503 klaidos kyla iš „OpenAI“, o ne iš tavęs. Tavo užklausa buvo teisinga, tačiau infrastruktūra jos negalėjo apdoroti. Bandyk iš naujo po delsos: daugeliu atvejų antras ar trečias bandymas būna sėkmingas.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 arba 503
print(f"Message: {e.message}")
# Veiksmas: bandyk iš naujo po delsos; klaida „OpenAI“ pusėje
Išsamus klaidų apdorotojas
Sujunkime šią elgseną į vieną funkciją. Logika yra triažas: fatalinės klaidos paverčiamos RuntimeError ir iškart iškeliamos, laikinos klaidos inicijuoja laukimą, kuris kiekvieną kartą dvigubėja, o jei bandymų limitas išsenka, kvietimas nepavyksta švariai, o ne grąžina tuščią reikšmę, kurią kviečiantysis gali neteisingai interpretuoti.
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 kvietimas su išsamiu klaidų apdorojimu."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Nekartokite – raktas neteisingas
raise RuntimeError("Neteisingas API raktas. Patikrinkite OPENAI_API_KEY.")
except BadRequestError as e:
# Nekartokite – užklausa suformuota neteisingai
raise RuntimeError(f"Neteisinga užklausa: {e.message}")
except RateLimitError:
# Kartokite taikydamas eksponentinį delsą
delay = 2 ** attempt
print(f"Pasiektas užklausų limitas. Laukiama {delay}s...")
time.sleep(delay)
except InternalServerError:
# Kartokite – serverio pusės klaida
delay = 2 ** attempt
print(f"Serverio klaida. Bandymas {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Kartokite – tinklo problema
delay = 2 ** attempt
print(f"Ryšio klaida. Bandymas {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Nepavyko po {max_retries} bandymų")
# Naudojimas
try:
result = robust_api_call("Labas!")
print(result)
except RuntimeError as e:
print(f"Fatalinė klaida: {e}")
„Responses“ API specifinės klaidos
Dvi situacijos nusipelno atskiro dėmesio, nes jos pasireiškia bendruoju kodu, tačiau reikalauja labai specifinio sprendimo.
Per ilgas kontekstas
Užuomina, viršijanti konteksto langą, grąžina 400 kodą, lygiai taip pat kaip ir rašybos klaida parametre. Norint atskirti šias dvi situacijas, reikia patikrinti pranešimą: jei jame yra context_length_exceeded, tai rodo, kad reikia sutrumpinti tekstą arba pereiti prie modelio su didesniu konteksto langu, o ne peržiūrėti parametrus.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Viršija konteksto langą
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("Užuomina per ilga šiam modeliui.")
print("Sprendimai: sutrumpinkite tekstą arba pasirinkite modelį")
print("su didesniu konteksto langu.")
Modelis nepasiekiamas
Modelių identifikatoriai nėra amžini. Diegimas, kuris vis dar nurodo pašalintą modelį, žlunga su 404 klaida, dėl ko visa programa sustoja, nors prieš dieną ji veikė. Apdorokite šį atvejį aiškiai: tai automatinis priminimas atnaujinti konfigūraciją.
try:
response = client.responses.create(
model="gpt-4-turbo", # pašalintas iš API 2026 m. spalio 23 d.
input="Test"
)
except NotFoundError as e:
print(f"Modelis nerastas: {e.message}")
print("Naudokite gpt-5.6-sol, „OpenAI“ nurodytą pakaitalą, arba naujesnį modelį.")
Struktūruotas klaidų registravimas
Neregistruota klaida yra tokia, apie kurią sužinosi tik iš kliento skundo. Registravimas JSON formatu, o ne laisvu tekstu, viską keičia, kai reikia agreguoti duomenis: gali suskaičiuoti 429 klaidas per valandą, filtruoti pagal response_id arba stebėti vartojimo pokyčius, ko neįmanoma padaryti su rankiniu būdu rašytomis žurnalo eilutėmis.
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 kvietimas su struktūruotu registravimu."""
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("Labas!")
Santraukos lentelė
Laikyk šią lentelę po ranka: joje apibendrintas sprendimas, kurį reikia priimti kiekvienam kodui.
| Kodas | Išimtis | Kartoti? | Veiksmas |
|---|---|---|---|
| 400 | BadRequestError | Ne | Ištaisyti užklausą |
| 401 | AuthenticationError | Ne | Patikrinti API raktą |
| 403 | PermissionDeniedError | Ne | Patikrinti leidimus |
| 404 | NotFoundError | Ne | Patikrinti modelį/galutinį tašką |
| 422 | UnprocessableEntityError | Ne | Ištaisyti formatą |
| 429 | RateLimitError | Taip | Eksponentinis delsa |
| 500 | InternalServerError | Taip | Palaukti ir bandyti iš naujo |
| 503 | InternalServerError | Taip | Laikinai nepasiekiama paslauga |
Svarbiausi punktai
- Klasifikuok klaidas: kartojamos (429, 500, 503) prieš fatalines (400, 401, 403)
- Kartojamoms klaidoms taikyk eksponentinį delsą
- Niekada nekartok autentifikacijos ar neteisingos užklausos klaidų
- Registruok kiekvieną klaidą su kontekstu (kodas, žinutė, laiko žyma)
- SDK automatiškai atlieka 2 pakartotinius bandymus – prireikus sukonfigūruok
max_retries