Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Immaniġġjar tal-Iżbalji u Kodiċijiet HTTP

Lezzjoni 12 / 22 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Immaniġġjar tal-Iżbalji u Kodiċijiet HTTP
  2. Kodiċijiet HTTP tal-API ta’ OpenAI
  3. Immaniġġjar Komprensiv tal-Iżbalji
  4. Iżbalji Speċifiċi għar-Responses API
  5. Reġistrazzjoni Strutturata tal-Iżbalji
  6. Tabella Sommarja
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI: temperature u top_p huma 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ċifikaw reasoning={"effort": "none"} (Responses API) jew reasoning_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ża gpt-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ċiEċċezzjoniIpprova mill-ġdid?Azzjoni
400BadRequestErrorLeIkkoreġi t-talba
401AuthenticationErrorLeIvverifika ċ-ċavetta tal-API
403PermissionDeniedErrorLeIvverifika l-permessi
404NotFoundErrorLeIvverifika l-mudell/l-endpoint
422UnprocessableEntityErrorLeIkkoreġi l-format
429RateLimitErrorIvaBackoff esponenzjali
500InternalServerErrorIvaStenna u pprova mill-ġdid
503InternalServerErrorIvaServizz 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_retries jekk meħtieġ