GuidesOneMux

OpenAI-API-Fehler sicher diagnostizieren: Authentifizierung, Ratenlimits, Timeouts und fehlerhafte Antworten

Ein praxisnaher, datenschutzbewusster Leitfaden zur Diagnose von Authentifizierungs-, Drosselungs-, Timeout- und fehlerhaften Antwortfehlern der OpenAI API, ohne Zugangsdaten oder Nutzerdaten offenzulegen.

AI

Zusammenfassung · TL;DR

Am sichersten lassen sich OpenAI-API-Fehler beheben, wenn Sie sie vor einem erneuten Versuch zunächst einordnen. Bei Authentifizierungsfehlern müssen meist Schlüssel, Organisation, Projekt oder IP-Konfiguration korrigiert werden. Ratenlimit- und Kontingentfehler erfordern eine Anpassung der Anfragerate oder administrative Änderungen. Timeouts können vorübergehend sein; fehlerhafte Antworten sollten als Transport-, Proxy- oder Parsing-Fehler untersucht werden. Protokollieren Sie Diagnosemetadaten, keine Zugangsdaten oder unbearbeiteten Nutzerinhalte.

Kernaussagen

  • Wiederholen Sie 401-Authentifizierungsfehler sowie Abrechnungs- und Kontingentfehler nicht so, als wären sie vorübergehende Netzwerkprobleme.
  • Beachten Sie bei 429-Drosselungs- und 503-Überlastungsantworten den Header `Retry-After`, sofern vorhanden, und verwenden Sie exponentielles Backoff mit begrenzter Anzahl von Versuchen.
  • Speichern Sie API-Schlüssel nicht im Quellcode, in Protokollen, Fehlermeldungen oder clientseitigen Anwendungen.
  • Behandeln Sie eine Nicht-JSON-Antwort oder einen fehlgeschlagenen JSON-Parse als separates Transport- oder Proxyproblem und erfassen Sie nur eine bereinigte, begrenzte Diagnose.
  • Geben Sie bei der Eskalation eines anhaltenden Problems das Modell, den Fehlercode, Zeitstempel, die Zeitzone und bereinigte Anfragedetails an.
Auf dieser Seite (7)

OpenAI-API-Fehler lassen sich leichter beheben, wenn Sie Konfigurationsfehler, Kapazitätsprobleme, Netzwerkfehler und Fehler beim Parsen der Antwort voneinander trennen. Die erste Diagnosefrage sollte lauten: Wird ein erneuter Versuch das Ergebnis wahrscheinlich ändern?

Ein 401-Fehler lässt sich in der Regel nicht durch einen erneuten Versuch beheben. Ein 429-Fehler aufgrund einer zu hohen Anfragerate kann sich nach einer Drosselung bessern. Ist dagegen das Guthaben aufgebraucht oder ein Ausgabenlimit erreicht, muss das Konto oder Projekt angepasst werden. Ein Timeout kann vorübergehend sein; wiederholte Timeouts können jedoch auf ein Netzwerk-, Proxy- oder Anfragegrößenproblem hindeuten.

Die folgenden Vorgehensweisen verwenden JavaScript und Konzepte der offiziellen OpenAI-Bibliothek, die im Leitfaden zu OpenAI-Fehlercodes beschrieben sind. Der Code veranschaulicht ein Muster und ist keine getestete Produktionsintegration.

Vor der Fehlersuche: Zugangsdaten und Nutzerdaten schützen

Beachten Sie diese Voraussetzungen, bevor Sie einen Fehler reproduzieren:

  • Speichern Sie den API-Schlüssel in einem serverseitigen Secret-Manager oder einer Umgebungsvariablen. Hinterlegen Sie ihn niemals in Browsercode, einer mobilen Anwendung, einer Versionsverwaltung oder einem Support-Ticket.
  • Protokollieren Sie einen Anfragezeitstempel, die Endpoint-Kategorie, die Modellkennung, den HTTP-Status und – falls verfügbar – den strukturierten Fehlercode.
  • Protokollieren Sie weder Authorization-Header noch vollständige Anfrage- oder Antwort-Bodys oder Prompts mit personenbezogenen Daten.
  • Wenn Sie für die Diagnose einen Prompt benötigen, erfassen Sie ein bereinigtes Beispiel oder eine stabile interne Anfragekennung anstelle des Originaltexts.
  • Begrenzen Sie die Länge von Diagnoseinhalten. Ein Proxy kann eine umfangreiche HTML-Fehlerseite zurückgeben; eine vorgelagerte Fehlermeldung kann außerdem Daten enthalten, die Sie nicht speichern wollten.

Eine hilfreiche Betriebsregel lautet: Protokolle sollen beantworten, was und wo fehlgeschlagen ist, ohne festzuhalten, was der Nutzer gesagt hat oder wie die Authentifizierung erfolgt.

Zuerst 401-Authentifizierungsfehler untersuchen

Zu den dokumentierten 401-Fällen zählen ungültige Authentifizierung, ein falscher API-Schlüssel, eine fehlende Organisationsmitgliedschaft und eine nicht autorisierte IP-Adresse. Ein 403-Fehler kann auf ein nicht unterstütztes Land, eine nicht unterstützte Region oder ein nicht unterstütztes Gebiet hinweisen.

Prüfen Sie die folgenden Punkte der Reihe nach:

  1. Vergewissern Sie sich, dass der Server das vorgesehene Secret liest und dieses weder abgeschnitten noch abgelaufen, widerrufen oder ersetzt wurde.
  2. Prüfen Sie, ob die Anfrage an den vorgesehenen API-Endpunkt und das richtige Projekt gesendet wird.
  3. Falls Ihre Konfiguration eine Organisationskennung oder eine IP-Zulassungsliste verwendet, gleichen Sie beides mit der Projektkonfiguration ab.
  4. Prüfen Sie, ob die Anfrage in der Entwicklungsumgebung, einem Container oder einer gehosteten Umgebung von einer anderen ausgehenden IP-Adresse stammt.
  5. Entfernen Sie alle Zugangsdaten aus der Debug-Ausgabe, bevor Sie Protokolle weitergeben.

Verwenden Sie für 401- oder 403-Fehler keine automatischen Wiederholungsversuche. Wiederholte Anfragen mit denselben ungültigen Zugangsdaten erzeugen unnötige Meldungen und können die Vorfallsanalyse erschweren. Korrigieren Sie die Konfiguration und senden Sie anschließend eine neue Anfrage.

429-Drosselung von Kontingent- und Abrechnungsfehlern unterscheiden

Nicht jeder 429-Fehler bedeutet „gleich noch einmal versuchen“. Der OpenAI-Leitfaden unterscheidet mehrere Fälle:

FehlerkategorieWahrscheinliche MaßnahmeAutomatischer erneuter Versuch?
Ratenlimit erreichtAnfragen drosseln und Retry-After beachten, falls vorhandenJa, begrenzt
slow_downAnfragerate reduzieren und schrittweise wieder erhöhenJa, vorsichtig
Guthaben aufgebrauchtGuthaben hinzufügenNein
Ausgabenlimit für Organisation oder ProjektDas zutreffende Limit ändernNein
Nutzungslimit der OrganisationEin höheres genehmigtes Limit beantragen oder den Support kontaktierenNein

Eine Wiederholungsschleife sollte den HTTP-Status und den konkreten Fehlercode prüfen, statt alle 429-Antworten gleich zu behandeln. Legen Sie eine maximale Anzahl von Versuchen fest und verwenden Sie exponentielles Backoff sowie Jitter, damit mehrere Worker nicht gleichzeitig erneut anfragen. Ist Retry-After vorhanden, richten Sie sich nach dieser Verzögerung, begrenzt durch Ihre eigene maximale Wartezeit.

Berücksichtigen Sie auch 503-Antworten. In der Quelldokumentation wird eine Modellüberlastung mit server_is_overloaded gekennzeichnet; vor einem erneuten Versuch wird empfohlen, Retry-After zu beachten, falls vorhanden. In der Python-Bibliothek kann eine Überlastung als InternalServerError dargestellt werden, während 429-Antworten RateLimitError verwenden. Gehen Sie in der Fehlerbehandlung nicht davon aus, dass Überlastungen immer als 429 eintreffen.

Timeouts und Verbindungsfehler untersuchen

Die offizielle Python-Bibliothek dokumentiert APITimeoutError für Anfragen, die wegen eines Timeouts fehlschlagen, und APIConnectionError für Verbindungsprobleme. Häufige Ansatzpunkte für die Diagnose sind:

  • Timeout vor einer Antwort: Prüfen Sie die Timeout-Einstellungen des Clients, Netzwerkwege, Proxys, Firewalls und die Anfragegröße.
  • Verbindungsfehler: Prüfen Sie DNS, TLS-Zertifikate, ausgehende Firewall-Regeln und die Proxy-Konfiguration.
  • Wiederholte serverseitige Fehler: Prüfen Sie die Statusseite des Dienstes und halten Sie bereinigte Zeitstempel für den Support fest.

Ein Timeout beweist nicht, dass der Server eine Anfrage nicht verarbeitet hat. Wenn doppelte Vorgänge relevant sind, gestalten Sie die Anwendung so, dass sich ein erneuter Versuch sicher abgleichen lässt – etwa indem Sie den Vorgang mit einem eigenen Anfragedatensatz verknüpfen. Beheben Sie Timeouts nicht, indem Sie das Timeout unbegrenzt erhöhen oder Versuche ohne Limit wiederholen.

Fehlerhafte Antworten behandeln, ohne Inhalte offenzulegen

„Fehlerhafte Antwort“ kann verschiedene Probleme bezeichnen: eine ungültige Anfrage, die einen BadRequestError auslöst, eine Antwort, die nicht dem erwarteten Schema entspricht, oder einen Proxy, der statt JSON HTML oder abgeschnittene Daten zurückgibt. Im OpenAI-Leitfaden wird BadRequestError als fehlerhafte oder unvollständige Anfrage beschrieben; empfohlen wird, erforderliche Parameter, Codierung, Format und Größe zu prüfen.

Bei direkten HTTP-Clients oder Middleware sollten Sie diese Prüfungen voneinander trennen:

  1. Prüfen Sie vor dem Parsen den HTTP-Status und Content-Type.
  2. Führen Sie das JSON-Parsing innerhalb eines abgesicherten Fehlerbehandlungsblocks aus.
  3. Prüfen Sie, ob die erforderlichen Felder vorhanden sind, bevor Sie sie verwenden.
  4. Erfassen Sie nur Status, Inhaltstyp, Antwortlänge und – sofern die Richtlinien es zulassen – einen begrenzten, bereinigten Ausschnitt.
  5. Nehmen Sie weder den API-Schlüssel noch den vollständigen Prompt oder die komplette Antwort in eine Parse-Fehlermeldung auf.

Ein beispielhafter Wrapper könnte so aussehen:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

Dieses Beispiel nimmt den Body bewusst nicht in die ausgelöste Fehlermeldung auf. Ergänzen Sie in der Produktion eine für den Endpunkt geeignete Schema-Validierung und speichern Sie unverarbeitete Nutzdaten nur im Rahmen eines kontrollierten, datenschutzrechtlich geprüften Diagnoseprozesses.

Muster für eine datenschutzbewusste Fehlerbehandlung

Das offizielle JavaScript-Beispiel unterscheidet zwischen Verbindungsfehlern, Ratenlimitfehlern und allgemeineren API-Fehlern. Bauen Sie darauf auf und klassifizieren Sie Fehler, ohne Secrets oder Nutzereingaben auszugeben:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

Prüfen Sie Klassennamen und Endpunktverhalten anhand der von Ihnen eingesetzten SDK-Version. Gehen Sie nicht davon aus, dass jeder anbieterkompatible Endpunkt alle SDK-Parameter oder Antwortfelder unterstützt.

Wann ein Problem eskaliert werden sollte

Bei anhaltenden Fehlern empfiehlt der OpenAI-Leitfaden, das Modell, die Fehlermeldung samt Fehlercode, Anfragedaten und Header, den Zeitstempel, die Zeitzone und weitere relevante Details bereitzustellen. Bereinigen Sie diese Angaben vorher: Ersetzen Sie Zugangsdaten, entfernen Sie Cookies, schwärzen Sie personenbezogene Daten und fassen Sie den Anfrage-Body nach Möglichkeit zusammen. Veröffentlichen Sie niemals vertrauliche Informationen in einem öffentlichen Forum.

Die praktische Entscheidung ist einfach: Korrigieren Sie Authentifizierungs- und Kontingentprobleme, drosseln Sie Anfragen bei Ratenlimits und Überlastungen, untersuchen Sie bei Timeouts die Netzwerkgrenzen und grenzen Sie Parsing-Fehler ein, ohne private Nutzdaten aufzubewahren.

FAQ

Sollte jede OpenAI-429-Antwort erneut versucht werden?

Nein. Antworten wegen Anfragerate oder `slow_down` sollten vorsichtig und mit Backoff erneut versucht werden; beachten Sie `Retry-After`, falls vorhanden. Wiederholungsversuche beheben weder aufgebrauchtes Guthaben noch Ausgaben- oder Nutzungslimits der Organisation.

Warum kann ein OpenAI-Überlastungsfehler als 503 statt als 429 auftreten?

Im OpenAI-Leitfaden wird eine Modellüberlastung als 503 mit dem Code `server_is_overloaded` dokumentiert. Die Fehlerbehandlung sollte sowohl Status als auch Code prüfen, statt davon auszugehen, dass Überlastung immer als Ratenlimit-Antwort auftritt.

Was sollte ich bei einem OpenAI-Authentifizierungsfehler protokollieren?

Protokollieren Sie Zeitstempel, Umgebung, Endpunktkategorie, Status und bereinigten Fehlercode. Protokollieren Sie weder den API-Schlüssel noch den `Authorization`-Header, den vollständigen Anfrage-Body oder den unbearbeiteten Nutzer-Prompt.

Wie untersuche ich eine ungültige JSON-Antwort?

Prüfen Sie vor dem Parsen den HTTP-Status und `Content-Type`. Erfassen Sie, sofern die Richtlinien es zulassen, nur eine begrenzte und bereinigte Diagnose. Untersuchen Sie außerdem Proxys oder Middleware, die möglicherweise HTML zurückgeben, Daten abschneiden oder die Antwort verändern.

Ähnliche Artikel