Fehlerbehandlung
Behandeln Sie API-Fehler, bevor sie Benutzer erreichen.
Erstellen Sie vorhersehbare Wiederherstellungspfade für Authentifizierungsfehler, Nutzungsregeln, Ratenbeschränkungen, Validierungsfehler und Abhängigkeitsfehler.
Zuletzt aktualisiert: July 12, 2026. Examples Nutzung safe placeholders und tun nicht enthalten real API-Schluessels oder customer Prompts.
Clientseitige Regel
Protokollieren Sie genügend Kontext, um den Fehler zu beheben, aber protokollieren Sie niemals rohe API-Schlüssel, Geheimnisse, Zahlungsdaten oder vollständige Kundenaufforderungen.
Fehlerkarte
Beginnen Sie mit der Fehlerklasse.
Die meisten Integrationsprobleme fallen in einen von fünf Kategorien. Klassifizieren Sie zunächst die Antwort und wählen Sie dann die nächste Aktion aus.
Authentifizierungsfehler
Bestätigen Sie den Autorisierungsheader, das Schlüsselformat, den aktiven Status, den Ablauf, die IP-Zulassungsliste und den erforderlichen Endpunktbereich, bevor Sie es erneut versuchen.
Kontingent überschritten
Kontingentfehler bedeuten, dass die Anfrage ein Paketlimit für Anfragen, Token oder Bilder überschreiten würde. Reduzieren Sie die Nutzung, warten Sie auf das Zurücksetzen oder ändern Sie die Paketkapazität.
Validierungsfehler
Ungültige JSON, fehlende Felder, nicht unterstützte Werte und fehlerhafte Nutzlasten sollten clientseitig behoben werden, bevor dieselbe Anfrage erneut gesendet wird.
Abhängigkeitsfehler
Eine interne Abhängigkeit oder ein Netzwerkpfad kann fehlschlagen, nachdem Ihre Anfrage angenommen wurde. Behandeln Sie vorübergehende 5xx-Fehler mit begrenzten Wiederholungsversuchen und sorgen Sie dafür, dass der Supportkontext geschwärzt bleibt.
Eskalation des Supports
Eskalieren Sie wiederholte Fehler mit Endpunkt, Zeitstempel, Status, Fehlercode, Umgebung, maskiertem Schlüsselpräfix und jeder Anforderungs-ID oder Anbieter-Trace-ID, wenn Routing aktiviert ist.
Antwortform
Analysieren Sie das OpenAI-kompatible Fehlerobjekt.
Check HTTP Status erste, dann branch auf error.code für Wiederherstellung path.
{
"error": {
"message": "Missing or invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key"
}
}| Status | Codes | Gemeinsame Ursache | Nächste Aktion |
|---|---|---|---|
| 400 | invalid_json, invalid_payload | Der Anforderungstext ist ungültig JSON oder stimmt nicht mit dem Endpunktschema überein. | Korrigieren Sie die Nutzlast und senden Sie sie erst erneut, nachdem die Validierung erfolgreich war. |
| 401 | invalid_api_key | Der API-Schlüssel fehlt, ist fehlerhaft oder wird nicht erkannt. | Überprüfen Sie das Bearer-Token, die Umgebungsvariable und das Schlüsselpräfix. |
| 402 | Abonnement_inaktiv, Abonnement_unverfügbar | Das mit dem Schlüssel verbundene Abonnement kann nicht auf API zugreifen. | Überprüfen Sie den Rechnungsstatus, bevor Sie weiteren kundenorientierten Datenverkehr senden. |
| 403 | inaktiver_api_key, abgelaufener_api_key, ip_not_allowed, unzureichender_Bereich | Der Schlüssel ist bekannt, wird jedoch durch Status, Ablauf, IP-Richtlinie oder Bereich blockiert. | Drehen oder aktualisieren Sie den Schlüssel und versuchen Sie es dann mit dem erforderlichen Bereich erneut. |
| 429 | request_quota_exceeded, token_quota_exceeded, image_quota_exceeded, quote_exceeded | Die Anfrage würde das Paketkontingent überschreiten. | Reduzieren Sie die Anfragegröße, warten Sie den Kontingentzeitraum ab oder wählen Sie ein größeres Paket. |
| 429 | rate_limit_exceeded | Der Anwendung sendet Anfragen schneller, als es die lokale Ratenbegrenzung zulässt. | Respektieren Sie „Retry-After“, sofern vorhanden, und verwenden Sie einen exponentiellen Wartezeit. |
| 501 | Streaming_not_enabled | Die angeforderte Funktion wird erkannt, ist aber für den Endpunkt nicht aktiviert. | Deaktivieren Sie die nicht unterstützte Option oder wenden Sie sich an den Kundendienst, wenn die Funktion erforderlich ist. |
| 5xx | Überprüfen Sie den Antworttext | Eine interne Abhängigkeit oder ein Netzwerkpfad ist fehlgeschlagen. | Wiederholen Sie die idempotente Arbeit mit Backoff und eskalieren Sie dann wiederholte Fehler mit Kontext. |
Führen Sie die Anleitung erneut aus
Wiederholen Sie nur die Fehler, die wiederhergestellt werden können.
Wiederholungsversuche helfen bei vorübergehenden Druck- oder Abhängigkeitsfehlern. Sie machen Validierungs-, Berechtigungs- und Abrechnungsprobleme noch lauter, wenn sich nichts ändert.
Versuchen Sie es erneut mit Backoff
429 rate_limit_exceeded, 408, 500, 502, 503, 504
Verwenden Sie einen begrenzten exponentiellen Wartezeit mit Jitter. Respektieren Sie „Retry-After“, wenn die Antwort es enthält.
Versuchen Sie es nicht unverändert erneut
400, 401, 402, 403, 501
Korrigieren Sie die Anfrage, den Schlüssel, den Abrechnungsstatus, die Berechtigung oder das Funktionsflag, bevor Sie denselben Anruf erneut versuchen.
Nach Kapazitätsänderungen erneut versuchen
429 Quotencodes
Kontingentfehler erfordern normalerweise kleinere Nutzlasten, verzögerte Arbeit oder eine Paketänderung anstelle sofortiger Wiederholungsversuche.
async function callWithBackoff(runRequest) {
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await runRequest();
if (response.ok) {
return response;
}
const retryable = [408, 429, 500, 502, 503, 504].includes(response.status);
if (!retryable) {
return response;
}
const retryAfter = Number(response.headers.get("retry-after") ?? 0);
const delayMs = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
return runRequest();
}Hinweise zur Implementierung
Halten Sie Wiederholungsversuche begrenzt, damit eine Benutzeraktion nicht zu einer Traffic-Spitze führen kann.
Fügen Sie Jitter bei Produktionsclients hinzu, die gleichzeitigen Datenverkehr senden.
Zeigen Sie nach dem letzten Wiederholungsversuch eine nützliche Benutzermeldung an, anstatt den Fehler zu verbergen.
Erfassen Sie geschwärzte Diagnosen, bevor die Wiederholungsschleife beendet wird.
Eskalation
Senden Sie der Unterstützung den Kontext, auf den sie reagieren kann.
Ein gutes Eskalationspaket verkürzt die Triage, ohne Geheimnisse, Eingabeaufforderungen oder Kundendaten preiszugeben.
Kundendienst kontaktierenFAQ
Fragen zur Fehlerbehandlung.
Welche Fehlerform sollte mein Kunde erwarten?
Der /v1 API gibt ein OpenAI-kompatibles JSON-Fehlerobjekt mit error.message, error.type und error.code zurück. Validierungsfehler können auch Details auf Feldebene umfassen.
Sollte ich es bei jeder 429-Antwort erneut versuchen?
Nein. Versuchen Sie kurze „rate_limit_exceeded“-Antworten mit „Retry-After“, sofern vorhanden. Reduzieren Sie bei Kontingentcodes die Nutzung, warten Sie auf das Zurücksetzen oder wählen Sie ein Paket mit mehr Kapazität.
War soll ich ein den Kundendienst senden?
Teilen Sie Endpunkt, Methode, Zeitstempel, Status, Fehlercode, maskiertes Schlüsselpräfix, Umgebung und jede Anforderungs-ID. Fügen Sie externe Trace-IDs nur hinzu, wenn der Kundendienst Sie dazu auffordert. Senden Sie keine rohen API-Schlüssel, Geheimnisse oder Kundenaufforderungen.
Kostenlose Tools
Debuggen Sie Fehler mit kostenlosen Tools
Suchen Sie nach Fehlercodes, dekodieren Sie 429-Antworten, simulieren Sie Wiederholungsversuche und planen Sie die Überwachung von Ratenbegrenzungen.
Fehlercodesuche
Suchen Sie nach unlimitedcodex-Fehlercodes, HTTP-Status, Wiederholungsanweisungen und Wiederherstellungsaktionen.
429-Decoder
Fügen Sie einen 429-Antworttext und Header ein, um Ratenbegrenzung und Kontingentdruck zu klassifizieren und die Anleitung für Wiederholungsversuche anzuzeigen.
Simulator erneut versuchen
Optimieren Sie die Backoff- und Wiederholungseinstellungen, um simulierte Ergebnisse anzuzeigen und einen Wiederholungshandler-Snippet zu kopieren.
Ratenlimit-Planer
Planen Sie Backoff-Einstellungen und eine Checkliste zur Quotenüberwachung anhand der erwarteten RPS und Teamgröße.