Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Foutafhandeling en HTTP-codes

Les 12 van 22 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Foutafhandeling en HTTP-codes
  2. HTTP-codes van de OpenAI API
  3. Uitgebreide foutafhandelaar
  4. Specifieke fouten van de Responses API
  5. Gestructureerde foutlogboekregistratie
  6. Overzichtstabel
  7. Belangrijkste punten

Bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie: temperature en top_p worden alleen geaccepteerd met een redeneerinspanning van none, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daarom reasoning={"effort": "none"} (Responses API) of reasoning_effort="none" (Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.

Verduidelijkt op 3 november 2026 op basis van de pagina Deprecations van OpenAI: het verwijderde modelvoorbeeld gebruikte eerder gpt-4o, dat beschikbaar blijft tot 14 januari 2027; het gebruikt nu gpt-4-turbo, dat op 23 oktober 2026 is stopgezet (aangegeven vervanging: gpt-5.6-sol). Bron: Deprecations.

Foutafhandeling en HTTP-codes

In productieomgevingen zijn fouten onvermijdelijk. Het netwerk valt uit, een API-sleutel verloopt, een collega implementeert een ongeldige parameter, of de API zelf kampt met een storing van drie minuten. Inzicht in de HTTP-codes die door de API worden geretourneerd en het correct afhandelen daarvan zijn essentieel voor het bouwen van robuuste applicaties. De hele uitdaging komt neer op één vraag die u bij elke uitzondering moet stellen: verdwijnt dit als ik het opnieuw probeer, of beland ik in een oneindige lus rond een probleem dat alleen een mens kan oplossen?

HTTP-codes van de OpenAI API

De API retourneert standaard HTTP-codes om het resultaat van elk verzoek aan te geven. De Python SDK laat u niet toe deze codes handmatig af te handelen; in plaats daarvan vertaalt deze elke code naar een getypeerde uitzondering die u afzonderlijk kunt opvangen. Hierdoor kunt u precieze except-blokken schrijven in plaats van een algemene except Exception die de aard van het probleem zou verhullen.

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

client = OpenAI()

401 — AuthenticationError

Een 401 geeft aan dat de API-sleutel ongeldig is of ontbreekt. U ziet dit doorgaans tijdens de eerste implementatie wanneer de omgevingsvariabele niet is doorgegeven aan de container. Opnieuw proberen is zinloos: de sleutel is over tien seconden nog steeds ongeldig.

try:
    # Ongeldige of ontbrekende API-sleutel
    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}")
    # Actie: verifieer de API-sleutel, genereer indien nodig opnieuw

400 — BadRequestError

Een 400 geeft aan dat het verzoek misvormd is. Hier wordt bijvoorbeeld een temperatuur van 5,0 opgegeven terwijl de maximaal geaccepteerde waarde 2,0 is. De foutmelding noemt bijna altijd de foutieve parameter, waardoor dit de snelst op te lossen fout is—mits u deze correct logt in plaats van stilzwijgend te negeren.

try:
    # Ongeldige parameters
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperatuur vereist effort none
        input="Test",
        temperature=5.0  # Ongeldige waarde (max 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Actie: corrigeer de verzoekparameters

429 — RateLimitError

Een 429 geeft aan dat u te veel verzoeken verzendt of uw quotum hebt overschreden. In tegenstelling tot de vorige twee is deze fout van tijdelijke aard: de teller wordt gereset. Dit is het schoolvoorbeeld voor een retry, maar dan een retry die wacht—en bij elke poging langer wacht.

try:
    # Te veel verzoeken of quotum overschreden
    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}")
    # Actie: wacht en probeer opnieuw met exponentiële backoff

500/503 — InternalServerError

Fouten 500 en 503 komen van OpenAI, niet van u. Uw verzoek was geldig; de infrastructuur kon het eenvoudigweg niet verwerken. Probeer het na een vertraging opnieuw: in de overgrote meerderheid van de gevallen slaagt de tweede of derde poging.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 of 503
    print(f"Message: {e.message}")
    # Actie: probeer opnieuw na een vertraging; de fout ligt aan de kant van OpenAI

Uitgebreide foutafhandelaar

Laten we dit gedrag samenvoegen in één functie. De logica is triage: fatale fouten worden omgezet in RuntimeError en direct gegenereerd, tijdelijke fouten activeren een wachttijd die bij elke beurt verdubbelt, en als het budget aan pogingen uitgeput is, faalt de aanroep netjes in plaats van een lege waarde terug te geven die de aanroeper verkeerd zou kunnen interpreteren.

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-aanroep met uitgebreide foutafhandeling."""

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

        except AuthenticationError:
            # Niet opnieuw proberen — de sleutel is ongeldig
            raise RuntimeError("Ongeldige API-sleutel. Controleer OPENAI_API_KEY.")

        except BadRequestError as e:
            # Niet opnieuw proberen — het verzoek is misvormd
            raise RuntimeError(f"Ongeldig verzoek: {e.message}")

        except RateLimitError:
            # Opnieuw proberen met exponentiële backoff
            delay = 2 ** attempt
            print(f"Ratelimit bereikt. Wachten {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Opnieuw proberen — serverfout
            delay = 2 ** attempt
            print(f"Serverfout. Poging {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Opnieuw proberen — netwerkprobleem
            delay = 2 ** attempt
            print(f"Verbindingsfout. Poging {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Mislukt na {max_retries} pogingen")

# Gebruik
try:
    result = robust_api_call("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Fatale fout: {e}")

Specifieke fouten van de Responses API

Twee situaties verdienen een aparte behandeling omdat ze onder een generieke code verschijnen maar om een zeer specifieke oplossing vragen.

Context te lang

Een prompt die het contextvenster overschrijdt, retourneert een 400, net als een typefout in een parameter. Om onderscheid te maken tussen de twee, inspecteert u het bericht: de aanwezigheid van context_length_exceeded wijst erop dat u de tekst moet inkorten of moet overschakelen op een model met een groter contextvenster, in plaats van uw parameters te controleren.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Overschrijdt contextvenster
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("De prompt is te lang voor dit model.")
        print("Oplossingen: kort de tekst in, of schakel over op een model")
        print("met een groter contextvenster.")

Model niet beschikbaar

Modelidentificatoren zijn niet eeuwig. Een implementatie die nog steeds verwijst naar een gepensioneerd model, faalt met een 404, waardoor de hele applicatie crasht terwijl deze de dag ervoor nog werkte. Handel dit geval expliciet af: het is een automatische herinnering om uw configuratie bij te werken.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # verwijderd uit de API op 23 oktober 2026
        input="Test"
    )
except NotFoundError as e:
    print(f"Model niet gevonden: {e.message}")
    print("Gebruik gpt-5.6-sol, de vervanging aangegeven door OpenAI, of een nieuwer model.")

Gestructureerde foutlogboekregistratie

Een fout die niet wordt gelogd, is een fout die u ontdekt via een ticket van een klant. Loggen in JSON in plaats van vrije tekst verandert alles wanneer u moet aggregeren: u kunt 429-fouten per uur tellen, filteren op response_id, of consumptieafwijkingen volgen, wat onmogelijk is met handgeschreven logregels.

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-aanroep met gestructureerde logboekregistratie."""
    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!")

Overzichtstabel

Houd dit overzicht bij de hand: het vat de te nemen beslissing voor elke code samen.

CodeUitzonderingOpnieuw proberen?Actie
400BadRequestErrorNeeVerzoek corrigeren
401AuthenticationErrorNeeAPI-sleutel verifiëren
403PermissionDeniedErrorNeeRechten verifiëren
404NotFoundErrorNeeModel/eindpunt verifiëren
422UnprocessableEntityErrorNeeFormaat corrigeren
429RateLimitErrorJaExponentiële backoff
500InternalServerErrorJaWachten en opnieuw proberen
503InternalServerErrorJaService tijdelijk niet beschikbaar

Belangrijkste punten

  • Categoriseer fouten: opnieuw probeerbaar (429, 500, 503) versus fataal (400, 401, 403)
  • Gebruik exponentiële backoff voor opnieuw probeerbare fouten
  • Probeer nooit authenticatie- of ongeldige verzoekfouten opnieuw
  • Log elke fout met context (code, bericht, tijdstempel)
  • De SDK handelt automatisch 2 retries af — configureer max_retries indien nodig