Fehlerbehandlung und HTTP-Codes
Auf dieser Seite
Aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation:
temperatureundtop_pwerden nur mit einem Reasoning-Effort vonnoneakzeptiert, während GPT-5.6-Modelle standardmäßig durch Reasoning arbeiten (medium). Aufrufe, die diese Parameter setzen, müssen daherreasoning={"effort": "none"}(Responses API) oderreasoning_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-4oauf, das bis zum 14. Januar 2027 weiterhin verfügbar ist. Es wird nungpt-4-turboverwendet, 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.
| Code | Ausnahme | Erneut versuchen? | Aktion |
|---|---|---|---|
| 400 | BadRequestError | Nein | Anfrage korrigieren |
| 401 | AuthenticationError | Nein | API-Schlüssel überprüfen |
| 403 | PermissionDeniedError | Nein | Berechtigungen überprüfen |
| 404 | NotFoundError | Nein | Modell/Endpunkt überprüfen |
| 422 | UnprocessableEntityError | Nein | Format korrigieren |
| 429 | RateLimitError | Ja | Exponentieller Backoff |
| 500 | InternalServerError | Ja | Warten und erneut versuchen |
| 503 | InternalServerError | Ja | Dienst 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_retriesbei Bedarf