Immaniġġjar tal-Iżbalji u Kodiċijiet HTTP
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI:
temperatureutop_phuma aċċettati biss b’sforz ta’ raġunar ta’none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod awtomatiku (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri għandhom jispeċifikawreasoning={"effort": "none"}(Responses API) jewreasoning_effort="none"(Chat Completions). Sorsi: L-użu ta’ GPT-6 · GPT-5.6 Terra.
Iċċarat fit-3 ta’ Novembru 2026 abbażi tal-paġna Deprecations ta’ OpenAI: l-eżempju tal-mudell imneħħi qabel kien juża
gpt-4o, li jibqa’ disponibbli sal-14 ta’ Jannar 2027; issa jużagpt-4-turbo, li ġie interrott fl-24 ta’ Ottubru 2026 (sostitut indikat:gpt-5.6-sol). Sors: Deprecations.
Immaniġġjar tal-Iżbalji u Kodiċijiet HTTP
Fil-produzzjoni, l-iżbalji huma inevitabbli. In-netwerk jaqa’, ċavetta tal-API tiskadi, kollega jiddispjaċċja parametru invalidu, jew l-API nnifisha tgħaddi minn tliet minuti ta’ interruzzjoni. Li tifhem il-kodiċijiet HTTP irritornati mill-API u li timmaniġġjahom sewwa huwa essenzjali biex tibni applikazzjonijiet robusti. L-isfida kollha tinġabar f’mistoqsija waħda li għandek tagħmel għal kull eċċezzjoni: dan se jisparixxi jekk nipprova mill-ġdid, jew se nidħol f’loop infinit fuq problema li biss bniedem jista’ jsolvi?
Kodiċijiet HTTP tal-API ta’ OpenAI
L-API tirritorna kodiċijiet HTTP standard biex tindika r-riżultat ta’ kull talba. L-SDK tal-Python ma jħallikx timmaniġġja dawn il-kodiċijiet manwalment; minflok, jittraduċi kull wieħed f’eċċezzjoni ttajpjata li tista’ taqbad separatament. Dan jippermettilek tikteb blokok except preċiżi minflok except Exception ġenerali li jkun jista’ jgħarraq in-natura tal-problema.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
401 jindika li ċ-ċavetta tal-API hija invalida jew nieqsa. Ġeneralment tara dan waqt l-ewwel dispjegament meta l-varjabbli tal-ambjent ma tkunx ġiet propagata fil-kontenitur. M’hemmx punt tipprova mill-ġdid: iċ-ċavetta se tkun daqstant invalida għaxar sekondi oħra.
try:
# Ċavetta tal-API invalida jew nieqsa
bad_client = OpenAI(api_key="sk-invalid")
bad_client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except AuthenticationError as e:
print(f"Kodiċi: {e.status_code}") # 401
print(f"Messaġġ: {e.message}")
# Azzjoni: ivverifika ċ-ċavetta tal-API, iġġedded jekk meħtieġ
400 — BadRequestError
400 jgħidlek li t-talba hija miktuba ħażin. Hawnhekk, temperatura ta’ 5.0 hija pprovduta meta l-valur massimu aċċettat huwa 2.0. Il-messaġġ ta’ żball kważi dejjem isemmi l-parametru difettuż, u dan jagħmilha l-aktar żball mgħaġġel biex issolvih—sakemm tirreġistrah sewwa minflok ma tibligħu silenzjużament.
try:
# Parametri invalidi
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # it-temperatura teħtieġ sforz none
input="Test",
temperature=5.0 # Valur invalidu (massimu 2.0)
)
except BadRequestError as e:
print(f"Kodiċi: {e.status_code}") # 400
print(f"Messaġġ: {e.message}")
# Azzjoni: ikkoreġi l-parametri tat-talba
429 — RateLimitError
429 jindika li qed tibgħat wisq talbiet jew li qbiżt il-kwota tiegħek. Kuntrarjament għaż-żewġ ta’ qabel, dan l-iżball huwa temporanju fin-natura tiegħu: il-kontatur jiġi rriżettjat. Dan huwa l-każ klassiku għal prova mill-ġdid, iżda prova li tistenna—u tistenna itwal ma’ kull tentattiv.
try:
# Wisq talbiet jew kwota mqabża
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except RateLimitError as e:
print(f"Kodiċi: {e.status_code}") # 429
print(f"Messaġġ: {e.message}")
# Azzjoni: stenna u pprova mill-ġdid b'backoff esponenzjali
500/503 — InternalServerError
L-iżbalji 500 u 503 ġejjin minn OpenAI, mhux minnek. It-talba tiegħek kienet valida; l-infrastruttura sempliċiment ma setgħetx tipproċessaha. Ipprova mill-ġdid wara dewmien: fil-biċċa l-kbira tal-każijiet, it-tieni jew it-tielet tentattiv jirnexxi.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Kodiċi: {e.status_code}") # 500 jew 503
print(f"Messaġġ: {e.message}")
# Azzjoni: ipprova mill-ġdid wara dewmien; l-iżball huwa fuq in-naħa ta' OpenAI
Immaniġġjar Komprensiv tal-Iżbalji
Ejja niġbru dawn l-imġieba f’funzjoni waħda. Il-loġika hija trijaġġ: l-iżbalji fatali jiġu kkonvertiti f’RuntimeError u mqajma immedjatament, l-iżbalji tranżitorji jattivaw stennija li tirdoppja f’kull dawra, u jekk il-baġit tat-tentattivi jintemm, is-sejħa tfalli b’mod nadir minflok ma tirritorna valur vojt li s-sejjaħ jista’ jinterpreta ħażin.
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:
"""Sejħa tal-API b'immaniġġjar komprensiv tal-iżbalji."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Tipprovax mill-ġdid — iċ-ċavetta hija invalida
raise RuntimeError("Ċavetta tal-API invalida. Iċċekkja OPENAI_API_KEY.")
except BadRequestError as e:
# Tipprovax mill-ġdid — it-talba hija miktuba ħażin
raise RuntimeError(f"Talba invalida: {e.message}")
except RateLimitError:
# Ipprova mill-ġdid b'backoff esponenzjali
delay = 2 ** attempt
print(f"Limitu tar-rata milħuq. Nistennew {delay}s...")
time.sleep(delay)
except InternalServerError:
# Ipprova mill-ġdid — żball fuq is-server
delay = 2 ** attempt
print(f"Żball tas-server. Tentattiv {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Ipprova mill-ġdid — problema fin-netwerk
delay = 2 ** attempt
print(f"Żball fil-konnessjoni. Tentattiv {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Falliment wara {max_retries} tentattivi")
# Użu
try:
result = robust_api_call("Hello!")
print(result)
except RuntimeError as e:
print(f"Żball fatali: {e}")
Iżbalji Speċifiċi għar-Responses API
Żewġ sitwazzjonijiet jistħoqqilhom trattament separat għax jidhru taħt kodiċi ġeneriku iżda jsejħu għal fix speċifiku ħafna.
Kuntest Twil Wisq
Prompt li jaqbeż it-tieqa tal-kuntest jirritorna 400, eżatt bħal żball fit-tip f’parametru. Biex tagħmel distinzjoni bejn iż-żewġ każijiet, eżamina l-messaġġ: il-preżenza ta’ context_length_exceeded tindirizzalek lejn it-tronkament tat-test jew il-bidla għal mudell b’tieqa tal-kuntest akbar, minflok ma tirrevedi l-parametri tiegħek.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Jaqbeż it-tieqa tal-kuntest
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("Il-prompt huwa twil wisq għal dan il-mudell.")
print("Soluzzjonijiet: ittronka t-test, jew ibdel għal mudell")
print("b'tieqa tal-kuntest akbar.")
Mudell Mhux Disponibbli
L-identifikaturi tal-mudelli mhumiex eterni. Dispjegament li għadu jirreferenzja mudell irtirat ifalli b’404, u jikkawża li l-applikazzjoni kollha taqa’ anke jekk kienet taħdem il-jum ta’ qabel. Immaniġġja dan il-każ b’mod espliċitu: huwa tfakkira awtomatika biex taġġorna l-konfigurazzjoni tiegħek.
try:
response = client.responses.create(
model="gpt-4-turbo", # irtirat mill-API fl-24 ta' Ottubru 2026
input="Test"
)
except NotFoundError as e:
print(f"Mudell ma nstabx: {e.message}")
print("Uża gpt-5.6-sol, is-sostitut indikat minn OpenAI, jew mudell iktar ġdid.")
Reġistrazzjoni Strutturata tal-Iżbalji
Żball mhux irreġistrat huwa żball li se tiskopri permezz ta’ tikketta tal-klijent. Ir-reġistrazzjoni f’JSON minflok test liberu tbiddel kollox meta jkollok bżonn taggrega: tista’ tgħodd il-429 kull siegħa, tiffiltra skont response_id, jew issegwi d-devjazzjoni tal-konsum, li huwa impossibbli b’linji tar-reġistru miktuba bl-idejn.
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:
"""Sejħa tal-API b'reġistrazzjoni strutturata."""
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!")
Tabella Sommarja
Żomm din il-grilja fil-qrib: tgħaqqad id-deċiżjoni li għandek tieħu għal kull kodiċi.
| Kodiċi | Eċċezzjoni | Ipprova mill-ġdid? | Azzjoni |
|---|---|---|---|
| 400 | BadRequestError | Le | Ikkoreġi t-talba |
| 401 | AuthenticationError | Le | Ivverifika ċ-ċavetta tal-API |
| 403 | PermissionDeniedError | Le | Ivverifika l-permessi |
| 404 | NotFoundError | Le | Ivverifika l-mudell/l-endpoint |
| 422 | UnprocessableEntityError | Le | Ikkoreġi l-format |
| 429 | RateLimitError | Iva | Backoff esponenzjali |
| 500 | InternalServerError | Iva | Stenna u pprova mill-ġdid |
| 503 | InternalServerError | Iva | Servizz temporanjament mhux disponibbli |
Punti Ewlenin
- Ikkategorizza l-iżbalji: li jistgħu jiġu ppruvati mill-ġdid (429, 500, 503) vs fatali (400, 401, 403)
- Uża backoff esponenzjali għal żbalji li jistgħu jiġu ppruvati mill-ġdid
- Qatt tipprovax mill-ġdid għal żbalji ta’ awtentikazzjoni jew talbiet invalidi
- Irreġistra kull żball bil-kuntest (kodiċi, messaġġ, timestamp)
- L-SDK jimmaniġġja awtomatikament 2 provi mill-ġdid — ikkonfigura
max_retriesjekk meħtieġ