Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Virheenkäsittely ja HTTP-koodit

Oppitunti 12 / 22 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Virheenkäsittely ja HTTP-koodit
  2. OpenAI API:n HTTP-koodit
  3. Kattava virheenkäsittelijä
  4. Responses API:n erityisvirheet
  5. Jäsennelty virhelokitus
  6. Yhteenvetotaulukko
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: temperature ja top_p hyväksytään vain, kun päättelypyrkimys (reasoning effort) on none, kun taas GPT-5.6-mallit päättelevät oletusarvoisesti (medium). Näitä parametreja asettavien kutsujen on siksi määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Selvennetty 3. marraskuuta 2026 OpenAI:n Deprecations-sivun perusteella: aiemmin käytetty poistettu malliesimerkki oli gpt-4o, joka on saatavilla vielä 14. tammikuuta 2027 saakka; se on nyt korvattu mallilla gpt-4-turbo, joka lopetettiin 23. lokakuuta 2026 (suositeltu korvaaja: gpt-5.6-sol). Lähde: Deprecations.

Virheenkäsittely ja HTTP-koodit

Tuotantoympäristössä virheet ovat väistämättömiä. Verkko pätkii, API-avain vanhentuu, kollega ottaa käyttöön virheellisen parametrin tai itse API kärsii kolmen minuutin katkoksesta. API:n palauttamien HTTP-koodien ymmärtäminen ja niiden oikea käsittely ovat ehdottoman tärkeitä robustien sovellusten rakentamisessa. Koko haaste tiivistyy yhteen kysymykseen, joka sinun on esitettävä jokaisen poikkeuksen kohdalla: katoaako tämä, jos yritän uudelleen, vai jäämmekö ikuiseen silmukkaan ongelmaan, jonka voi ratkaista vain ihminen?

OpenAI API:n HTTP-koodit

API palauttaa standardoituja HTTP-koodeja ilmoittaakseen jokaisen pyynnön tuloksen. Python-SDK ei anna sinun käsitellä näitä koodeja manuaalisesti; sen sijaan se muuntaa jokaisen niistä tyypitetyksi poikkeukseksi, jonka voit siepata erikseen. Tämä mahdollistaa tarkkojen except-lohkojen kirjoittamisen sen sijaan, että käyttäisit kaiken nielevää except Exception -lohkoa, joka hämärtäisi ongelman luonteen.

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

client = OpenAI()

401 — AuthenticationError

401-koodi kertoo, että API-avain on virheellinen tai puuttuu. Tämä ilmenee tyypillisesti ensimmäisen käyttöönoton yhteydessä, kun ympäristömuuttujaa ei ole levitetty konttiin. Uudelleenyritys on turha: avain on yhtä virheellinen kymmenen sekunnin kuluttua.

try:
    # Virheellinen tai puuttuva API-avain
    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}")
    # Toimenpide: tarkista API-avain, luo uusi tarvittaessa

400 — BadRequestError

400-koodi kertoo pyynnön olevan virheellisesti muotoiltu. Tässä esimerkissä lämpötilaksi (temperature) on annettu 5.0, vaikka suurin hyväksytty arvo on 2.0. Virheilmoitus nimeää lähes aina viallisen parametrin, mikä tekee tästä nopeimmin korjattavan virheen – edellyttäen, että kirjaat sen oikein etkä niele sitä hiljaisesti.

try:
    # Virheelliset parametrit
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature vaatii effort-arvon none
        input="Test",
        temperature=5.0  # Virheellinen arvo (max 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Toimenpide: korjaa pyynnön parametrit

429 — RateLimitError

429-koodi kertoo, että lähetät liian monta pyyntöä tai olet ylittänyt kiintiösi. Toisin kuin kaksi edellistä, tämä virhe on luonteeltaan väliaikainen: laskuri nollautuu. Tämä on oppikirjaesimerkki tilanteesta, jossa kannattaa yrittää uudelleen, mutta odottaa – ja odottaa entistä pidempään jokaisella yrityksellä.

try:
    # Liian monta pyyntöä tai kiintiö ylitetty
    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}")
    # Toimenpide: odota ja yritä uudelleen eksponentiaalisella viiveellä

500/503 — InternalServerError

500- ja 503-virheet tulevat OpenAI:lta, eivät sinulta. Pyyntösi oli kelvollinen, mutta infrastruktuuri ei pystynyt käsittelemään sitä. Yritä uudelleen viiveen jälkeen: valtaosassa tapauksia toinen tai kolmas yritys onnistuu.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 tai 503
    print(f"Message: {e.message}")
    # Toimenpide: yritä uudelleen viiveen jälkeen; virhe on OpenAI:n puolella

Kattava virheenkäsittelijä

Yhdistetään nämä käyttäytymismallit yhdeksi funktioksi. Logiikka on triage: kohtalokkaat virheet muunnetaan RuntimeError-poikkeuksiksi ja nostetaan välittömästi, ohimenevät virheet käynnistävät odotuksen, joka kaksinkertaistuu jokaisella kierroksella, ja jos yritysbudjetti loppuu, kutsu epäonnistuu siististi sen sijaan, että se palauttaisi tyhjän arvon, jonka kutsuja saattaisi tulkita väärin.

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-kutsu kattavalla virheenkäsittelyllä."""

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

        except AuthenticationError:
            # Älä yritä uudelleen — avain on virheellinen
            raise RuntimeError("Virheellinen API-avain. Tarkista OPENAI_API_KEY.")

        except BadRequestError as e:
            # Älä yritä uudelleen — pyyntö on virheellisesti muotoiltu
            raise RuntimeError(f"Virheellinen pyyntö: {e.message}")

        except RateLimitError:
            # Yritä uudelleen eksponentiaalisella viiveellä
            delay = 2 ** attempt
            print(f"Nopeusrajoitus saavutettu. Odotetaan {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Yritä uudelleen — palvelinvirhe
            delay = 2 ** attempt
            print(f"Palvelinvirhe. Yritys {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Yritä uudelleen — verkkovirhe
            delay = 2 ** attempt
            print(f"Yhteysvirhe. Yritys {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Epäonnistui {max_retries} yrityksen jälkeen")

# Käyttö
try:
    result = robust_api_call("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Kohtalokas virhe: {e}")

Responses API:n erityisvirheet

Kaksi tilannetta ansaitsee erillisen käsittelyn, koska ne esiintyvät yleisen koodin alla, mutta vaativat hyvin spesifiä korjausta.

Konteksti liian pitkä

Kehote, joka ylittää konteksti-ikkunan, palauttaa 400-koodin aivan kuten parametri kirjoitusvirheineen. Näiden erottamiseksi tarkista viesti: context_length_exceeded-merkkijonon esiintyminen ohjaa sinut lyhentämään tekstiä tai vaihtamaan malliin, jolla on suurempi konteksti-ikkuna, sen sijaan että tarkistaisit parametrisi.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Ylittää konteksti-ikkunan
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Kehote on liian pitkä tälle mallille.")
        print("Ratkaisut: lyhennä tekstiä tai vaihda malliin,")
        print("jolla on suurempi konteksti-ikkuna.")

Malli ei saatavilla

Mallitunnisteet eivät ole ikuisia. Käyttöönotto, joka viittaa edelleen eläköityneeseen malliin, epäonnistuu 404-virheellä, mikä kaataa koko sovelluksen, vaikka se olisi toiminut edellisenä päivänä. Käsittele tämä tapaus erikseen: se on automaattinen muistutus konfiguraation päivittämisestä.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # poistettu API:sta 23. lokakuuta 2026
        input="Test"
    )
except NotFoundError as e:
    print(f"Mallia ei löytynyt: {e.message}")
    print("Käytä gpt-5.6-sol-mallia, jonka OpenAI on ilmoittanut korvaajaksi, tai uudempaa mallia.")

Jäsennelty virhelokitus

Lokittamaton virhe on virhe, jonka huomaat vasta asiakasticketin kautta. Lokitus JSON-muodossa vapaan tekstin sijaan muuttaa kaiken, kun tietoja on aggregoitava: voit laskea 429-virheet tuntikohtaisesti, suodattaa response_id:n perusteella tai seurata kulutuksen muutoksia, mikä on mahdotonta käsin kirjoitetuilla lokiriveillä.

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-kutsu jäsennellyllä lokituksella."""
    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!")

Yhteenvetotaulukko

Pidä tämä ruudukko käsillä: se tiivistää jokaiselle koodille tehtävän päätöksen.

KoodiPoikkeusUudelleenyritys?Toimenpide
400BadRequestErrorEiKorjaa pyyntö
401AuthenticationErrorEiTarkista API-avain
403PermissionDeniedErrorEiTarkista käyttöoikeudet
404NotFoundErrorEiTarkista malli/päätepiste
422UnprocessableEntityErrorEiKorjaa muoto
429RateLimitErrorKylläEksponentiaalinen takautus
500InternalServerErrorKylläOdota ja yritä uudelleen
503InternalServerErrorKylläPalvelu ei ole väliaikaisesti käytettävissä

Keskeiset asiat

  • Luokittele virheet: uudelleenyrityksen arvoiset (429, 500, 503) vs kohtalokkaat (400, 401, 403)
  • Käytä eksponentiaalista viivettä uudelleenyrityksiä vaativissa virheissä
  • Älä koskaan yritä uudelleen tunnistautumis- tai virheellisiä pyyntöjä koskevissa virheissä
  • Lokita jokainen virhe kontekstin kera (koodi, viesti, aikaleima)
  • SDK käsittelee automaattisesti 2 uudelleenyritystä – määritä max_retries tarvittaessa