GPT-6 Astra API-Fehler: 15 häufige Probleme und wie man sie behebt

Der schnellste Weg, einen API-Vorfall zu verschlimmern, ist, jeden Fehler erneut zu versuchen. Ein fehlerhaftes Schema heilt nicht durch Backoff, und ein erschöpftes Guthaben erholt sich nicht, weil ein Arbeiter es zehn weitere Male versucht hat. Diagnostizieren Sie Fehler anhand des HTTP-Status, der SDK-Klasse, des error.type und insbesondere des error.code.

Ein sicherer Fehlerbehandler

try {
  return await client.responses.create({
    model: "gpt-6-astra",
    Eingabe
  });
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    // Network, proxy, TLS, DNS or firewall path.
  } else if (error instanceof OpenAI.RateLimitError) {
    // Inspect code and Retry-After before deciding to retry.
  } else if (error instanceof OpenAI.APIError) {
    console.error(error.status, error.message, error.code);
  } sonst {
    throw error;
  }
}

Protokollieren Sie die Anfrage-ID, Zeitstempel und Zeitzone, Modell, Endpunkt, Status, Code, Wiederholungsanzahl und bereinigte Payload-Merkmale. Protokollieren Sie standardmäßig niemals API-Schlüssel oder vertrauliche Prompt-Inhalte.

1. 400 Bad Request

Die Nutzlast ist fehlerhaft oder inkompatibel: falsches Feld, fehlende Eingabe, ungültiges Tool-Schema, nicht unterstützte Kombination oder schlecht codierter Inhalt. Lesen Sie die Nachricht, vergleichen Sie sie mit der aktuellen Responses-Referenz und fügen Sie Vertragstests hinzu. Wiederholen Sie die unveränderte Eingabe nicht.

2. 401 Authentifizierungsfehler

Der Schlüssel oder Token ist ungültig, abgelaufen, widerrufen oder falsch gesendet. Bestätige die Geheimnisinjektion und Projektumgebung. Ersetze exponierte Schlüssel; drucke sie niemals beim Debuggen aus.

3. 401 Falsche Organisation oder Projekt

Ein gültiger Schlüssel kann dennoch den falschen Bereich anvisieren. Überprüfen Sie die Projektkonfiguration und etwaige explizite Organisations-/Projekt-Header. Stimmen Sie den Schlüssel, die Ressource und den Abrechnungsbereich ab.

4. 401 IP nicht autorisiert

Die Anfragequelle stimmt nicht mit der konfigurierten Zulassungsliste überein. Senden Sie von einer genehmigten Ausgangs-IP oder aktualisieren Sie die Zulassungsliste über autorisierte Verwaltung. Ein erneuter Versuch von derselben Quelle bewirkt nichts.

5. 403 Zugriff verweigert oder nicht unterstützte Region

Dem Anrufer fehlt der Zugriff auf die Ressource, das Modell oder die Region. Überprüfen Sie die Projektrolle, die Modellverfügbarkeit, die Ressourceninhaberschaft und die Regeln für unterstützte Länder. Verschleiern Sie ein Berechtigungsproblem in internen Protokollen nicht als „nicht gefunden“.

6. 404 Nicht gefunden

Eine Antwort, Konversation, Vektorspeicher, Datei oder andere Kennung ist falsch, abgelaufen oder nicht zugänglich. Bestätigen Sie die genaue ID und das Projekt. Vermeiden Sie bei Benutzerinteraktionen, die Existenz von Ressourcen außerhalb des Benutzerbereichs preiszugeben.

7. 409 Konflikt

Eine andere Anfrage hat die Ressource gleichzeitig geändert. Laden Sie den aktuellen Zustand neu, wenden Sie die beabsichtigte Änderung auf die neue Version an und verwenden Sie optimistisches Sperren oder Idempotenz. Blindes sofortiges Wiederholen kann den Konflikt wiederholen.

8. 422 Unprocessable Entity

Das Format ist syntaktisch akzeptabel, aber der Dienst kann es nicht verarbeiten. Überprüfen Sie Größen, Kodierungen, Dateistatus und Feldkombinationen. Die offizielle Tabelle empfiehlt einen erneuten Versuch, aber beseitigen Sie zuerst deterministische Ursachen.

9. 429 Anfrage- oder Token-Ratenbegrenzung

Drosseln Sie den Datenverkehr und befolgen Sie Retry-After, falls vorhanden. Verwenden Sie andernfalls begrenztes exponentielles Backoff mit Jitter. Koordinieren Sie Wiederholungsbudgets über Worker hinweg, damit diese keine Stampede verursachen. Reduzieren Sie redundante Aufrufe und große Token-Bursts.

10. 429 `slow_down`

Dies ist ein Ramp-Rate-Signal: Der Datenverkehr wuchs zu schnell, auch wenn die offensichtlichen Grenzwerte ausreichend erscheinen. Befolgen Sie Retry-After, reduzieren Sie die Anforderungsrate und erhöhen Sie sie dann schrittweise. Die aktuelle Anleitung von OpenAI gibt als Faustregel vor, dass nach Erreichen von einer Million Eingabe-Token pro Minute das Wachstum nicht mehr als 50 % alle 15 Minuten betragen sollte; die tatsächliche Aktivierung variiert je nach Modell und Bedingungen.

11. 429 Kredit-, Ausgaben- oder Nutzungslimit

Codes enthalten credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded und organization_usage_limit_exceeded. Diese erfordern Guthaben oder Limitänderungen. Ein erneuter Versuch kann den Zugriff nicht wiederherstellen. Benachrichtigen Sie einen Eigentümer und schlagen Sie schnell fehl.

12. 500 Interner Serverfehler

Wiederholen Sie nach einer kurzen Wartezeit mit einem begrenzten Budget und überprüfen Sie die Statusseite, falls Fehler bestehen bleiben. Erfassen Sie die Anfrage-ID für den Support. Bei einem zustandsändernden Workflow gleichen Sie die Nebeneffekte des Tools ab, bevor Sie die gesamte Anfrage erneut abspielen.

13. 503 Modell überlastet

Der dokumentierte Typ/Code ist service_unavailable_error / server_is_overloaded. Beachten Sie Retry-After oder reduzieren Sie die Anfragen, wenn dieser fehlt. Beachten Sie, dass die aktuelle Python-SDK-Anleitung zwischen RateLimitError für 429 und InternalServerError für 503 unterscheidet; fangen Sie beide ab, wenn Ihre Überlastungslogik zuvor davon ausging, dass jedes Kapazitätsproblem ein 429 war.

14. Verbindungs- oder Zeitüberschreitungsfehler

APIConnectionError kann auf Netzwerk-, Proxy-, TLS-Zertifikats-, DNS- oder Firewall-Probleme hinweisen. APITimeoutError bedeutet, dass die Frist abgelaufen ist. Wiederholen Sie sichere Lesevorgänge, überprüfen Sie die Unternehmens-Proxy-Einstellungen und vermeiden Sie die Deaktivierung der TLS-Überprüfung. Bei Schreibvorgängen stellen Sie fest, ob der Vorgang vor dem Wiederholen stattgefunden hat.

15. WebSocket-Status und Streaming-Fehler

previous_response_not_found bedeutet, dass der referenzierte Status nicht aufgelöst werden kann; offizielle Anleitung besagt, den vollständigen Eingabekontext mit previous_response_id auf null gesetzt erneut zu senden. websocket_connection_limit_reached spiegelt das 60-minütige Verbindungslimit wider; öffnen Sie eine neue Verbindung und fahren Sie fort. Behandeln Sie außerdem response.failed, response.incomplete und Transport-error-Ereignisse, statt anzunehmen, dass das Schließen des Sockets einem Abschluss gleichkommt.

Eine Wiederholungsmatrix

Wiederholungsversuche und gesamte verstrichene Wiederholungszeit. Verwenden Sie einen Unterbrechungsschalter bei weitreichenden Vorfällen und einen Dead-Letter-Pfad für Aufträge, die eine Überprüfung durch den Bediener erfordern. Wiederholungen sollten beobachtbar sein, nicht versteckt in verschachtelten SDK- und Anwendungsschleifen.

FAQ

Sollte ich jeden 429 erneut versuchen?

Nein. Tarif- und Rampenfehler können nach der erforderlichen Verzögerung erneut versucht werden; Guthaben-, Ausgaben- und Nutzungslimitfehler erfordern eine Kontomaßnahme.

Warum die Anfrage-ID aufzeichnen?

Es ermöglicht dem Support und Ihrer eigenen Telemetrie, einen Fehler mit einer bestimmten API-Anfrage zu korrelieren, ohne die vollständige Nutzlast offenzulegen.

Kann ich einen zeitlich abgelaufenen Tool-Aufruf wiederholen?

Erst nachdem festgestellt wurde, ob es einen Nebeneffekt verursacht hat. Verwenden Sie Idempotenzschlüssel und Abgleich vor erneutem Versuch.

Was sollten Benutzer sehen?

Eine präzise, handlungsorientierte Nachricht und gegebenenfalls eine sichere Wiederholungsoption. Bewahren Sie Stack-Traces, Anbieter-Codes und sensible Details in geschützten Diagnosedaten auf.

Fazit

Zuverlässige GPT-6 Astra-Fehlerbehandlung beginnt mit der Klassifizierung. Beheben Sie deterministische 4xx-Anfragen, unterscheiden Sie Ratenauslastung von Abrechnungsgrenzen, fahren Sie bei vorübergehenden 5xx-Fehlern zurück, gleichen Sie unsichere Schreibvorgänge ab und modellieren Sie Streaming als Zustandsmaschine. Eine begrenzte Wiederholungsrichtlinie zusammen mit guter anfragebezogener Telemetrie löst mehr Vorfälle als wahllose Wiederholungen es jemals tun werden.