GuidesOneMux

OpenAI-API-Fehler in der Produktion: sicher diagnostizieren, erneut versuchen und wiederherstellen

Ein praxisorientierter Produktionsworkflow zur Diagnose von OpenAI-Authentifizierungs-, Ratenlimit-, Timeout-, Server- und fehlerhaften Antwortproblemen – und zur Entscheidung, ob ein erneuter Versuch, eine Korrektur oder eine Wiederherstellung nötig ist.

AI

Zusammenfassung · TL;DR

Eine zuverlässige Fehlerbehandlung in der Produktion beginnt damit, den Fehler zu klassifizieren – nicht damit, jede Anfrage erneut zu senden. Dieser Leitfaden unterscheidet Konfigurations- und Kontingentfehler von vorübergehender Drosselung, Timeouts, Serverfehlern und ungültigen Antworten. Anschließend folgen ein begrenztes JavaScript-Muster für Wiederholungsversuche und eine Checkliste zur Wiederherstellung.

Kernaussagen

  • Authentifizierungs-, Berechtigungs-, fehlerhafte Anfragen oder aufgebrauchte Guthaben nicht erneut versuchen, bevor die Ursache behoben wurde.
  • Bei Ratenlimits und Überlastung `Retry-After` beachten, sofern vorhanden, und die Wiederholungsversuche mit exponentiellem Backoff und Jitter begrenzen.
  • Ein Timeout beweist nicht, dass der Vorgang fehlgeschlagen ist. Nicht idempotente Arbeit nicht blind wiederholen.
  • Erfolgreiche Antworten validieren, bevor der nachgelagerte Workflow-Status übernommen wird, und genügend Kontext für eine sichere Wiederherstellung aufbewahren.
Auf dieser Seite (6)

Die Produktionsregel: erst klassifizieren, dann erneut versuchen

Wenn ein Aufruf der OpenAI API fehlschlägt, lautet die hilfreiche Frage nicht einfach: „Soll ich es erneut versuchen?“ Sondern: „Welche Anzeichen sprechen dafür, dass der Fehler vorübergehend ist, und was würde eine doppelte Anfrage bewirken?“ Ein Workflow für die Produktion sollte den Fehler klassifizieren, eine begrenzte Maßnahme ergreifen und den Status des Jobs bewahren, wenn eine sichere Fortsetzung nicht möglich ist.

OpenAI dokumentiert unterschiedliche Ursachen für Authentifizierungsfehler, Ratenlimits, aufgebrauchte Guthaben oder Ausgabenlimits, Serverfehler und überlastete Modelle. Der Statuscode allein reicht nicht immer aus: Prüfen Sie auch Fehlercode und Fehlermeldung. Im Leitfaden zu OpenAI-Fehlercodes finden Sie die dokumentierten Ursachen und Abhilfemaßnahmen.

Fehler nach Typ einordnen

SymptomWahrscheinliche MaßnahmeErneut versuchen?
401-AuthentifizierungsfehlerPrüfen, ob der API-Schlüssel korrekt und aktiv ist und die vorgesehene Organisation verwendet wird. Falls konfiguriert, auch die IP-Zulassungsliste überprüfen.Nein, erst nach Korrektur der Zugangsdaten oder des Zugriffs.
400 Bad RequestFehlermeldung und Anfrageparameter prüfen, einschließlich erforderlicher Eingaben, Codierung, Format und Größe.Nein, erst nach Korrektur der Anfrage.
429-Ratenlimit oder „slow down“Parallelität oder Anfragerate verringern. Retry-After beachten, sofern vorhanden, und den Datenverkehr anschließend schrittweise erhöhen.Ja, innerhalb einer begrenzten Wiederholungsrichtlinie.
429-Guthaben-, Ausgaben- oder Nutzungslimiterror.code prüfen und Guthaben wiederherstellen oder das betreffende Limit beheben.Nein. Durch Wiederholen derselben Anfrage wird der Zugriff nicht wiederhergestellt.
500-Serverfehler oder 503-ÜberlastungKurz warten, Retry-After beachten, sofern vorhanden, und die Anfrage innerhalb eines Limits wiederholen.In der Regel ja, mit Schutzmaßnahmen.
Client-Timeout oder VerbindungsfehlerNetzwerk-, Proxy-, TLS- und Firewall-Bedingungen prüfen und feststellen, ob die Anfrage möglicherweise bereits abgeschlossen wurde.Manchmal; zunächst mögliche Folgen doppelter Ausführung berücksichtigen.
Erfolgreicher Status, aber unbrauchbare AntwortAntwortstruktur und erforderliche Felder validieren, bevor der Workflow fortgesetzt wird.Nicht automatisch. Als separaten Datenqualitäts- oder Protokollfehler behandeln.

Laut OpenAI-Leitfaden entspricht RateLimitError in Python dem Status 429 und InternalServerError dem Status 503. Eine Überlastung kann daher mit einem anderen Statuscode auftreten, als ein vorhandener Handler erwartet. Verwenden Sie unabhängig vom Client sowohl den Status als auch die Fehlerdetails, statt anzunehmen, dass jede Überlastung als 429 gemeldet wird.

Ein begrenztes JavaScript-Muster für Wiederholungsversuche

Voraussetzungen: ein aktuelles OpenAI-JavaScript-SDK, ein konfigurierter API-Schlüssel und ein Workflow, der sicher beurteilen kann, ob eine wiederholte Anfrage zulässig ist. Dieses illustrative Beispiel wiederholt nur ausgewählte vorübergehende Fehler. Es beweist nicht, dass eine Anfrage nach einem Timeout nicht verarbeitet wurde.

import OpenAI from "openai";

const client = new OpenAI();

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryAfterMs(error) {
  const value = error.headers?.get?.("retry-after");
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const dateMs = Date.parse(value);
  return Number.isNaN(dateMs) ? null : Math.max(0, dateMs - Date.now());
}

function isRetryable(error) {
  const code = error.code;
  if ([
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
  ].includes(code)) return false;

  return error instanceof OpenAI.RateLimitError ||
    (error instanceof OpenAI.APIError &&
      [500, 503].includes(error.status));
}

async function createResponseWithRetry(input, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.responses.create({
        model: "YOUR_MODEL",
        input,
      });
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;

      const exponentialMs = Math.min(10_000, 500 * 2 ** attempt);
      const jitterMs = Math.floor(Math.random() * 250);
      const delayMs = retryAfterMs(error) ?? exponentialMs + jitterMs;
      await sleep(delayMs);
    }
  }
}

YOUR_MODEL ist ein Platzhalter und keine Modellempfehlung. Das Beispiel veranschaulicht die Steuerung von Wiederholungsversuchen, nicht ein über alle SDK-Versionen und Endpunkte hinweg getestetes Verhalten. Prüfen Sie, ob das SDK in Ihrer installierten Version Antwort-Header wie dargestellt bereitstellt. Falls nicht, verwenden Sie den unterstützten Mechanismus, um sie auszulesen. Legen Sie neben der Anzahl der Wiederholungsversuche auch eine Deadline auf Workflow-Ebene fest, damit ein festgefahrener Job nicht unbegrenzt wartet.

Nehmen Sie Authentifizierungs-, Bad-Request-, Berechtigungs- oder Kontingentfehler nicht in isRetryable auf. Beheben Sie zuerst die Konfiguration oder den Zugriff. Erwägen Sie außerdem ein Wiederholungsbudget pro Job und ein Parallelitätslimit auf Warteschlangenebene: Wenn jeder Worker sofort erneut versucht, können Wiederholungen eine Lastspitze verstärken.

Für Timeouts und fehlerhafte Antworten sind Wiederherstellungsregeln nötig

Ein Timeout bedeutet, dass der Client nicht rechtzeitig eine Antwort erhalten hat. Daraus lässt sich nicht ableiten, ob der Server den Vorgang abgeschlossen hat. Entscheiden Sie vor einem erneuten Versuch, ob doppelte Arbeit akzeptabel ist. Speichern Sie bei Jobs mit folgenreichen nachgelagerten Aktionen eine Job-ID und den Verarbeitungsstatus. Gestalten Sie nachgelagerte Schreibvorgänge nach Möglichkeit idempotent. Ist das Ergebnis ungewiss, markieren Sie den Job zur Abstimmung, statt unüberlegt wiederholt Arbeit anzustoßen.

Behandeln Sie die Antwortvalidierung als eigenen Schritt im Workflow. Prüfen Sie, ob das Antwortobjekt vorhanden ist, ob der erwartete Inhalt vorliegt und ob strukturierte Ausgaben geparst werden können und dem Schema Ihrer Anwendung entsprechen. Eine Antwort, die die Validierung nicht besteht, darf nicht als erfolgreiches Ergebnis übernommen werden. Protokollieren Sie sichere Diagnoseinformationen und leiten Sie den Fall anschließend an einen begrenzten Korrektur- oder Prüfpfad weiter. Gehen Sie nicht davon aus, dass eine identische Anfrage durch Wiederholung fehlerhafte Inhalte korrigiert.

Checkliste für den Betrieb

  1. Protokollieren Sie Zeitstempel und Zeitzone, Endpunkt, Modell, HTTP-Status, Fehlertyp und Fehlercode sowie eine sichere Korrelations-ID für die Anfrage.
  2. Protokollieren Sie niemals API-Schlüssel oder sensible Eingaben. Bewahren Sie nur die Anfrageinformationen auf, die für eine sichere Reproduktion des Fehlers erforderlich sind.
  3. Wiederholen Sie nur vorübergehende Fehler und legen Sie eine maximale Anzahl von Versuchen, Verzögerung, Jitter und eine Gesamtdauer fest.
  4. Beachten Sie Retry-After, falls angegeben, und drosseln Sie den Datenverkehr weiter, wenn die Begrenzung anhält.
  5. Trennen Sie ausgeschöpfte Wiederholungsversuche von dauerhaften Fehlern, damit Operatoren geeignete Jobs prüfen und erneut ausführen können.
  6. Erfassen Sie bei anhaltenden Fehlern das Modell, die Fehlermeldung und den Fehlercode, Anfragedaten und Header ohne Geheimnisse, Zeitstempel und Zeitzone sowie weitere relevante Informationen. OpenAI empfiehlt, diese Angaben dem Support bereitzustellen.

Fazit

Zuverlässige OpenAI-API-Workflows unterscheiden vorübergehende Auslastung von Fehlern, die eine Änderung an der Konfiguration oder einem Limit erfordern. Drosselungs- und Dienstfehler sollten sorgfältig erneut versucht werden; Authentifizierungs- und Anfragefehler müssen behoben werden. Behandeln Sie Timeouts und ungültige Ausgaben als ausdrückliche Wiederherstellungszustände. Mit dieser Einordnung verhindern Sie, dass eine Wiederholungsschleife aus einem einzelnen fehlgeschlagenen Aufruf einen größeren Produktionsvorfall macht.

FAQ

Sollte ich jede 429-Antwort der OpenAI API erneut versuchen?

Nein. Ratenlimit-Antworten sollten mit angemessenen Abständen, einer begrenzten Anzahl von Versuchen und `Retry-After`, sofern vorhanden, erneut versucht werden. Ein 429 aufgrund aufgebrauchter Guthaben oder eines Ausgaben- oder Nutzungslimits erfordert die Behebung dieses Limits. Durch Wiederholen des Aufrufs wird der Zugriff nicht wiederhergestellt. Prüfen Sie den Fehlercode.

Wie sollte ein Workflow mit einem Timeout der OpenAI API umgehen?

Behandeln Sie das Ergebnis als ungewiss: Der Client kann ein Timeout erhalten haben, obwohl die Verarbeitung abgeschlossen wurde. Berücksichtigen Sie vor einem erneuten Versuch mögliche doppelte Auswirkungen, verwenden Sie nach Möglichkeit idempotente nachgelagerte Vorgänge und leiten Sie unklare Jobs zur Abstimmung weiter.

Was sollte ich tun, wenn die API eine fehlerhafte Antwort zurückgibt?

Validieren Sie Antwortstruktur und erforderliche Felder, bevor Sie die Antwort speichern oder darauf reagieren. Übernehmen Sie den Job nicht in den Erfolgsstatus, protokollieren Sie sichere Diagnoseinformationen und nutzen Sie einen kontrollierten Korrektur- oder Prüfpfad, statt automatisch dieselbe Anfrage erneut zu senden.

Bedeutet ein 503 dasselbe wie ein 429?

Nein. Laut den hier angeführten OpenAI-Informationen stehen 429-Antworten für Ratenlimits und 503-Antworten für eine Überlastung des Modells; es handelt sich um unterschiedliche Fälle. Ein Client sollte Status und Fehlerdetails prüfen und beide Fälle bei Bedarf behandeln, statt davon auszugehen, dass eine Überlastung immer als 429 erscheint.

Ähnliche Artikel