Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Fehlerbehandlung und HTTP-Codes

Lektion 12 von 22 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Fehlerbehandlung und HTTP-Codes
  2. HTTP-Codes der OpenAI API
  3. Umfassender Fehlerhandler
  4. Spezifische Fehler der Responses API
  5. Strukturierte Fehlerprotokollierung
  6. Zusammenfassungstabelle
  7. Wichtige Erkenntnisse

Aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation: temperature und top_p werden nur mit einem Reasoning-Effort von none akzeptiert, während GPT-5.6-Modelle standardmäßig durch Reasoning arbeiten (medium). Aufrufe, die diese Parameter setzen, müssen daher reasoning={"effort": "none"} (Responses API) oder reasoning_effort="none" (Chat Completions) angeben. Quellen: Using GPT-6 · GPT-5.6 Terra.

Klarstellung am 3. November 2026 basierend auf der Deprecations-Seite von OpenAI: Das zuvor verwendete Beispiel für ein entferntes Modell wies gpt-4o auf, das bis zum 14. Januar 2027 weiterhin verfügbar ist. Es wird nun gpt-4-turbo verwendet, das am 23. Oktober 2026 eingestellt wurde (angegebener Ersatz: gpt-5.6-sol). Quelle: Deprecations.

Fehlerbehandlung und HTTP-Codes

In der Produktion sind Fehler unvermeidbar. Das Netzwerk bricht zusammen, ein API-Schlüssel läuft ab, ein Kollege deployt einen ungültigen Parameter, oder die API selbst leidet unter einem dreiminütigen Ausfall. Das Verständnis der von der API zurückgegebenen HTTP-Codes und deren korrekte Handhabung ist unerlässlich für den Aufbau robuster Anwendungen. Die gesamte Herausforderung lässt sich auf eine einzige Frage reduzieren, die Sie für jede Ausnahme stellen müssen: Wird dieses Problem verschwinden, wenn ich es erneut versuche, oder werde ich in einer Endlosschleife auf ein Problem laufen, das nur ein Mensch beheben kann?

HTTP-Codes der OpenAI API

Die API gibt standardmäßige HTTP-Codes zurück, um das Ergebnis jeder Anfrage anzugeben. Das Python-SDK lässt Sie diese Codes nicht manuell verarbeiten; stattdessen übersetzt es jeden in eine typisierte Ausnahme, die Sie separat abfangen können. Dies ermöglicht es Ihnen, präzise except-Blöcke zu schreiben, anstatt einen allgemeinen except Exception, der die Natur des Problems verschleiern würde.

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

client = OpenAI()

401 — AuthenticationError

Ein 401 gibt an, dass der API-Schlüssel ungültig oder fehlt. Dies sehen Sie typischerweise bei der ersten Bereitstellung, wenn die Umgebungsvariable noch nicht im Container propagiert wurde. Ein erneuter Versuch ist nutzlos: Der Schlüssel wird in zehn Sekunden genauso ungültig sein.

try:
    # Ungültiger oder fehlender API-Schlüssel
    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}")
    # Aktion: Überprüfen Sie den API-Schlüssel und regenerieren Sie ihn bei Bedarf

400 — BadRequestError

Ein 400 gibt an, dass die Anfrage fehlerhaft ist. Hier wird beispielsweise ein temperature-Wert von 5,0 angegeben, während der maximal akzeptierte Wert 2,0 beträgt. Die Fehlermeldung benennt fast immer den fehlerhaften Parameter, was dies zur schnellsten zu behebbenden Ausnahme macht – vorausgesetzt, Sie protokollieren sie korrekt und verschlucken sie nicht stumm.

try:
    # Ungültige Parameter
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature erfordert effort none
        input="Test",
        temperature=5.0  # Ungültiger Wert (Max 2,0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Aktion: Korrigieren Sie die Anfrageparameter

429 — RateLimitError

Ein 429 gibt an, dass Sie zu viele Anfragen senden oder Ihr Kontingent überschritten haben. Im Gegensatz zu den beiden vorherigen ist dieser Fehler von Natur aus vorübergehend: Der Zähler wird zurückgesetzt. Dies ist der Lehrbuchfall für einen erneuten Versuch, jedoch einen Versuch, der wartet – und bei jedem weiteren Versuch länger wartet.

try:
    # Zu viele Anfragen oder Kontingent überschritten
    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}")
    # Aktion: Warten und erneut versuchen mit exponentiellem Backoff

500/503 — InternalServerError

Fehler 500 und 503 stammen von OpenAI, nicht von Ihnen. Ihre Anfrage war gültig; die Infrastruktur konnte sie einfach nicht verarbeiten. Versuchen Sie es nach einer Verzögerung erneut: In den meisten Fällen gelingt der zweite oder dritte Versuch.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 oder 503
    print(f"Message: {e.message}")
    # Aktion: Nach einer Verzögerung erneut versuchen; der Fehler liegt auf der Seite von OpenAI

Umfassender Fehlerhandler

Bringen wir diese Verhaltensweisen in einer einzigen Funktion zusammen. Die Logik ist eine Triage: Kritische Fehler werden in RuntimeError umgewandelt und sofort geworfen, vorübergehende Fehler lösen ein Warten aus, das bei jedem Durchlauf verdoppelt wird, und wenn das Budget für Versuche erschöpft ist, schlägt der Aufruf sauber fehl, anstatt einen leeren Wert zurückzugeben, den der Aufrufer missinterpretieren könnte.

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-Aufruf mit umfassender Fehlerbehandlung."""

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

        except AuthenticationError:
            # Nicht erneut versuchen — der Schlüssel ist ungültig
            raise RuntimeError("Ungültiger API-Schlüssel. Prüfen Sie OPENAI_API_KEY.")

        except BadRequestError as e:
            # Nicht erneut versuchen — die Anfrage ist fehlerhaft
            raise RuntimeError(f"Ungültige Anfrage: {e.message}")

        except RateLimitError:
            # Erneut versuchen mit exponentiellem Backoff
            delay = 2 ** attempt
            print(f"Rate Limit erreicht. Warten {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Erneut versuchen — Serverseitiger Fehler
            delay = 2 ** attempt
            print(f"Serverfehler. Versuch {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Erneut versuchen — Netzwerkproblem
            delay = 2 ** attempt
            print(f"Verbindungsfehler. Versuch {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Fehlgeschlagen nach {max_retries} Versuchen")

# Verwendung
try:
    result = robust_api_call("Hallo!")
    print(result)
except RuntimeError as e:
    print(f"Fehler: {e}")

Spezifische Fehler der Responses API

Zwei Situationen verdienen eine gesonderte Behandlung, da sie unter einem allgemeinen Code erscheinen, aber eine sehr spezifische Lösung erfordern.

Kontext zu lang

Ein Prompt, der das Kontextfenster überschreitet, gibt einen 400 zurück, genau wie ein Tippfehler in einem Parameter. Um zwischen beiden zu unterscheiden, inspizieren Sie die Meldung: Das Vorhandensein von context_length_exceeded weist Sie darauf hin, den Text zu kürzen oder auf ein Modell mit einem größeren Kontextfenster umzusteigen, anstatt Ihre Parameter zu überprüfen.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Überschreitet das Kontextfenster
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Der Prompt ist für dieses Modell zu lang.")
        print("Lösungen: Kürzen Sie den Text oder wechseln Sie zu einem Modell")
        print("mit einem größeren Kontextfenster.")

Modell nicht verfügbar

Modell-Identifikatoren sind nicht ewig gültig. Ein Deployment, das noch auf ein zurückgezogenes Modell verweist, schlägt mit einem 404 fehl und führt dazu, dass die gesamte Anwendung abstürzt, obwohl sie noch am Vortag funktioniert hat. Behandeln Sie diesen Fall explizit: Es ist eine automatische Erinnerung, Ihre Konfiguration zu aktualisieren.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # Am 23. Oktober 2026 aus der API zurückgezogen
        input="Test"
    )
except NotFoundError as e:
    print(f"Modell nicht gefunden: {e.message}")
    print("Verwenden Sie gpt-5.6-sol, den von OpenAI angegebenen Ersatz, oder ein neueres Modell.")

Strukturierte Fehlerprotokollierung

Ein nicht protokollierter Fehler ist ein Fehler, den Sie über einen Kundenticket erst entdecken. Die Protokollierung in JSON statt als freier Text ändert alles, wenn Sie aggregieren müssen: Sie können 429er pro Stunde zählen, nach response_id filtern oder Verbrauchsdrifts tracken, was mit handgeschriebenen Logzeilen unmöglich ist.

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-Aufruf mit strukturierter Protokollierung."""
    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("Hallo!")

Zusammenfassungstabelle

Behalten Sie dieses Raster griffbereit: Es fasst die Entscheidung für jeden Code zusammen.

CodeAusnahmeErneut versuchen?Aktion
400BadRequestErrorNeinAnfrage korrigieren
401AuthenticationErrorNeinAPI-Schlüssel überprüfen
403PermissionDeniedErrorNeinBerechtigungen überprüfen
404NotFoundErrorNeinModell/Endpunkt überprüfen
422UnprocessableEntityErrorNeinFormat korrigieren
429RateLimitErrorJaExponentieller Backoff
500InternalServerErrorJaWarten und erneut versuchen
503InternalServerErrorJaDienst vorübergehend nicht verfügbar

Wichtige Erkenntnisse

  • Kategorisieren Sie Fehler: erneut versuchbar (429, 500, 503) vs. kritisch (400, 401, 403)
  • Verwenden Sie exponentiellen Backoff für erneut versuchbare Fehler
  • Versuchen Sie Authentifizierungs- oder ungültige Anfragefehler niemals erneut
  • Protokollieren Sie jeden Fehler mit Kontext (Code, Meldung, Zeitstempel)
  • Das SDK behandelt standardmäßig 2 Versuche – konfigurieren Sie max_retries bei Bedarf