Virheenkäsittely ja HTTP-koodit
Tällä sivulla
Päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella:
temperaturejatop_phyväksytään vain, kun päättelypyrkimys (reasoning effort) onnone, 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) taireasoning_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 mallillagpt-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.
| Koodi | Poikkeus | Uudelleenyritys? | Toimenpide |
|---|---|---|---|
| 400 | BadRequestError | Ei | Korjaa pyyntö |
| 401 | AuthenticationError | Ei | Tarkista API-avain |
| 403 | PermissionDeniedError | Ei | Tarkista käyttöoikeudet |
| 404 | NotFoundError | Ei | Tarkista malli/päätepiste |
| 422 | UnprocessableEntityError | Ei | Korjaa muoto |
| 429 | RateLimitError | Kyllä | Eksponentiaalinen takautus |
| 500 | InternalServerError | Kyllä | Odota ja yritä uudelleen |
| 503 | InternalServerError | Kyllä | 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_retriestarvittaessa