code entscheiden, wie sie reagiert. Die Raten-, Größen-, Token- und Budgetlimits, die vielen dieser Fehler zugrunde liegen, finden Sie unter Limits und faire Nutzung.
Format der Fehlerantwort
Wenn eine Anfrage fehlschlägt, gibt die API einen HTTP-Fehlerstatus und diesen Body zurück:
Der Body enthält kein Feld
param und keine Angaben dazu, welcher Teil der Anfrage den Fehler verursacht hat. Um die Ursache zu finden, vergleichen Sie Ihre Anfrage mit Chat Completions.
Fehler in gestreamten Antworten
Beistream: true hängt es vom Zeitpunkt des Fehlers ab, wo er erscheint:
- Bevor der Stream beginnt: Sie erhalten einen normalen JSON-Fehler mit einem HTTP-Fehlerstatus, wie oben gezeigt.
- Nachdem der Stream begonnen hat: Der HTTP-Status ist bereits
200. Der Fehler kommt daher als Event im Stream an. Die OpenAI-SDKs lösen beim Lesen des Streams eine Ausnahme aus.
APIError-Ausnahme aus, die zwar code enthält, aber keinen Statuscode. Fangen Sie daher APIError ab, nicht nur APIStatusError. In Node.js ist error.status bei einem Stream-Fehler undefined.
Ein Fehler während eines Streams hat meist den Code API_UPSTREAM_REJECTED. Sie können auch API_USAGE_IDENTITY_UNVERIFIED erhalten. Das bedeutet, dass DeepMask einen Stream gestoppt hat, den es nicht verifizieren konnte. In beiden Fällen wurde möglicherweise bereits ein Teil der Antwort erzeugt, daher ist das Ergebnis der Anfrage unklar. DeepMask berechnet die Anfrage nicht, es sei denn, für sie wird später noch Nutzung gemeldet. Für sich allein pausiert sie die Anfragen Ihrer Organisation in der Regel nicht. Wiederholen Sie die Anfrage nicht in einer Schleife. Mehr als 20 unklare Ergebnisse innerhalb von 24 Stunden pausieren die Anfragen Ihrer Organisation. Siehe Werden fehlgeschlagene Anfragen abgerechnet? und Unklare Ergebnisse.
Erreicht eine gestreamte Anfrage die maximale Anfragedauer von 15 Minuten, schließt DeepMask die Verbindung ohne Fehler-Event. Mit cURL oder einem anderen HTTP-Client endet der Stream ohne data: [DONE]. Die OpenAI-SDKs verarbeiten data: [DONE] selbst und zeigen es Ihnen nie an. Bei den SDKs löst das Lesen des Streams stattdessen einen Verbindungsfehler aus, oder der Stream endet vorzeitig. Prüfen Sie in jedem Fall, ob der Stream einen Chunk mit finish_reason enthalten hat. Behandeln Sie einen Stream ohne einen solchen Chunk als unvollständig. Auch ein so abgebrochener Stream hat ein unklares Ergebnis. DeepMask berechnet ihn nicht, es sei denn, für ihn wird später noch Nutzung gemeldet.
Fehlercodes
Die folgenden Tabellen sind nach HTTP-Status gruppiert.400 und 413: ungültige Anfrage
401: ungültige Anmeldedaten
402: Zahlung erforderlich
403: Zugriff verweigert
404: Endpunkt nicht gefunden
Eine Anfrage an einen Pfad außerhalb von
/v1/, auch an /v1 allein, gibt 404 mit einem leeren Body statt JSON zurück. Prüfen Sie, ob Ihre Basis-URL https://api.deepmask.io/v1 lautet.
409: in Kürze erneut versuchen
429: Raten- und Kapazitätslimits
Die Standardwerte und die Funktionsweise der einzelnen Limits finden Sie unter Limits und faire Nutzung.
Ausgabenlimits: 400 oder 429
Eine Ablehnung wegen eines Ausgabenlimits kann den Status
400 oder 429 haben. Eine Wiederholung hilft erst, wenn das Limit geändert oder zurückgesetzt wurde. Siehe Ausgabenlimits.
Anbieterfehler: 4xx, 502 oder 503
Bei
API_UPSTREAM_REJECTED stammt ein Status 401, 403 oder 404 vom Modellanbieter und liegt nicht an Ihrem Schlüssel oder Pfad. Versuchen Sie es später erneut oder wenden Sie sich an den Support, wenn der Fehler anhält.
Der Anbieter kann auch ein Bild ablehnen, das er nicht verarbeiten kann, zum Beispiel ein GIF, das er nicht decodieren kann. Es fallen keine Kosten an, und die Ablehnung zählt nicht als unklares Ergebnis. Bei gpt-4o und gpt-4.1 ist der Status der eigene 4xx-Status des Anbieters. Bei den Claude-Modellen kann er auch 502 lauten, und diesen Status wiederholen die OpenAI-SDKs automatisch. Eine Wiederholung mit demselben Bild hilft nicht. Schlägt eine Anfrage mit einem Bild immer wieder mit API_UPSTREAM_REJECTED fehl, prüfen Sie das Bild, zum Beispiel indem Sie es in ein statisches PNG umwandeln.
503 und 504: vorübergehend nicht verfügbar
Erhalten Sie einen Code, der hier nicht aufgeführt ist, behandeln Sie ihn anhand seines HTTP-Status. Wiederholen Sie
409-, 429- und 5xx-Antworten mit Backoff und wenden Sie sich an den Support, wenn der Fehler anhält.Fehlgeschlagene Anfragen wiederholen
Welche Fehler Sie wiederholen sollten
Wiederholungen in den OpenAI-SDKs
Die OpenAI-SDKs für Python und Node.js wiederholen409-, 429- und 5xx-Antworten automatisch. Standardmäßig unternehmen sie zwei Wiederholungsversuche mit exponentiellem Backoff und Jitter. Um das zu ändern, setzen Sie max_retries (Python) bzw. maxRetries (Node.js) im Client.
Jede automatische Wiederholung ist eine neue Anfrage. Schlägt eine Anfrage mit 502 oder 504 fehl, zählt jede Wiederholung, die auf dieselbe Weise fehlschlägt, als weiteres unklares Ergebnis. Eine nach 504 wiederholte Anfrage kann außerdem noch einmal 15 Minuten laufen. Mit max_retries=4 wie in den Beispielen unten kann ein einzelner Aufruf daher bis zu fünfmal auf Ihr 24-Stunden-Kontingent angerechnet werden.
Die SDKs wiederholen jede 429-Antwort, auch Ablehnungen wegen eines Ausgabenlimits. Eine durch ein Ausgabenlimit blockierte Anfrage wird daher möglicherweise wiederholt, bevor der Fehler Ihren Code erreicht.
Außerdem brechen die SDKs standardmäßig nach 10 Minuten mit einem Timeout ab und wiederholen die Anfrage dann. Eine DeepMask-Anfrage kann bis zu 15 Minuten laufen. Setzen Sie den Client-Timeout daher etwas höher: timeout=960 in Python (Sekunden) oder timeout: 960_000 in Node.js (Millisekunden). Sonst kann das SDK eine noch laufende Anfrage aufgeben und erneut senden.
Eigene Wiederholungslogik
Wenn Sie Wiederholungen selbst implementieren, verwenden Sie exponentielles Backoff mit Jitter:- Warten Sie vor der ersten Wiederholung etwa eine Sekunde.
- Verdoppeln Sie die Wartezeit nach jedem fehlgeschlagenen Versuch, bis zu einer Obergrenze von beispielsweise 30 Sekunden.
- Addieren Sie zu jeder Wartezeit einen zufälligen Anteil, damit parallele Clients ihre Anfragen nicht im selben Moment wiederholen.
- Brechen Sie nach einigen Versuchen ab und melden Sie den Fehler.
Retry-After, warten Sie mindestens so viele Sekunden, wie dort angegeben sind.
Um 429-Fehler von vornherein zu vermeiden, begrenzen Sie, wie viele Anfragen Ihre Anwendung parallel ausführt. Überschreiten Sie dabei Ihren Wert für Gleichzeitige Anfragen nicht, zum Beispiel mithilfe einer Warteschlange oder eines Semaphors. Beispiele finden Sie unter Parallele Anfragen in Ihrer Anwendung begrenzen.
Fehler im Code behandeln
Das cURL-Beispiel gibt den HTTP-Status nach dem Antwort-Body aus. Die SDK-Beispiele setzen einen Timeout über der maximalen Anfragedauer von 15 Minuten und wiederholen fehlgeschlagene Anfragen automatisch. Schlägt eine Anfrage trotzdem fehl, werten die Beispieleerror.code aus. Das Node.js-Beispiel verwendet Top-Level-await. Führen Sie es daher als ES-Modul aus, zum Beispiel als .mjs-Datei.
Werden fehlgeschlagene Anfragen abgerechnet?
Eine Anfrage mit unklarem Ergebnis pausiert die Anfragen Ihrer Organisation für sich allein in der Regel nicht. DeepMask berechnet sie nicht, aber der Anbieter hat die Antwort nach dem Fehler möglicherweise trotzdem fertiggestellt. Trifft die Nutzung für die Anfrage später ein, rechnet DeepMask sie wie jede andere Nutzung ab. Eine Anfrage, die
502 oder 504 zurückgegeben hat, oder ein abgebrochener Stream kann daher trotzdem in Ihrer Nutzung erscheinen. Kann DeepMask diese Nutzung nicht verifizieren, zum Beispiel weil sie als fehlgeschlagener Versuch erfasst ist, prüft DeepMask sie zuerst. Während der Prüfung sind Ihre Anfragen pausiert. Siehe Wann Anfragen pausiert werden.
Über dem 24-Stunden-Kontingent von 20 unklaren Ergebnissen werden die Anfragen Ihrer Organisation pausiert. Siehe Unklare Ergebnisse.
Wann Anfragen pausiert werden
DeepMask pausiert die API-Anfragen Ihrer Organisation, während es eine Anfrage oder erfasste Nutzung prüft, bevor feststeht, was berechnet wird. Häufige Ursachen sind:- Viele unklare Ergebnisse: Ihre Organisation hat ihr 24-Stunden-Kontingent von 20 unklaren Ergebnissen überschritten. Jedes weitere pausiert Ihre Anfragen, bis DeepMask es geklärt hat. Siehe Unklare Ergebnisse.
- Nutzung, die geprüft werden muss: DeepMask kann erfasste Nutzung noch nicht verifizieren oder ihren Preis noch nicht bestimmen. Beispiele sind Nutzung, die nicht zur Anfrage passt, Nutzung, die als fehlgeschlagener Versuch erfasst ist, Nutzung für eine Anfrage, die DeepMask oder der Modellanbieter abgelehnt hat, und Nutzung, die nach dem Ende der API-Abrechnung erfasst wurde. Einige dieser Prüfungen werden von selbst abgeschlossen, zum Beispiel sobald DeepMask den aktuellen Preis eines Modells bestätigt hat.
- Verspätete Nutzung: Eine Anfrage wurde abgeschlossen, aber ihre Nutzung ist 15 Minuten nach dem Start der Anfrage noch nicht eingetroffen. Diese Pause endet von selbst, sobald die Nutzung eintrifft.
503 mit API_ADMISSION_UNAVAILABLE zurück. Eine Anfrage, die bereits in Bearbeitung war, erhält stattdessen API_ACCOUNTING_REVIEW. Die Seite API zeigt den Hinweis „API-Anfragen sind pausiert, während die letzte Nutzung geprüft wird. Wenden Sie sich an DeepMask, falls das anhält.“
Ganz zu Beginn einer Pause kann eine Anfrage auch 503 mit API_RESERVATION_REVIEW zurückgeben. Behandeln Sie diesen Code wie API_ACCOUNTING_REVIEW.
Während DeepMask erfasste Nutzung prüft, kann die Registerkarte Nutzung außerdem eine Warnung wie „Anfragen in Prüfung: 2. Die Summe dieses Monats kann sich noch ändern.“ anzeigen. Auch bei einer Pause nach vielen unklaren Ergebnissen kann diese Warnung erscheinen, muss es aber nicht. Siehe Anfragen in Prüfung.
Einige Prüfungen werden innerhalb von Minuten von selbst abgeschlossen. Andere muss DeepMask klären. Eine Pause nach unklaren Ergebnissen über dem 24-Stunden-Kontingent endet nicht von selbst. Wenden Sie sich daher an den Support, wenn Ihre Anfragen pausiert bleiben. Wiederholen Sie Anfragen nicht in einer Schleife, solange sie pausiert sind. Bei anderen Ursachen wenden Sie sich an den Support, wenn der Hinweis länger als einige Minuten bestehen bleibt. Direkt nach dem Ende einer Pause können Anfragen kurzzeitig 503 mit API_ADMISSION_UNAVAILABLE zurückgeben, während die Änderung umgesetzt wird.
Fehlerbehebung
Jede Anfrage gibt401 mit API_CREDENTIAL_INVALID zurück? Prüfen Sie, ob Sie Authorization: Bearer <key> genau einmal senden und ob der Schlüssel mit sk- beginnt. Bitten Sie einen Administrator, die Registerkarte Schlüssel zu prüfen. Ein widerrufener Schlüssel erscheint unter Widerrufene Schlüssel und kann nicht wiederhergestellt werden. Erstellen Sie bei Bedarf einen neuen Schlüssel.
Anfragen schlagen direkt nach dem Aktivieren der Abrechnung fehl? DeepMask richtet Ihr API-Abonnement möglicherweise noch ein. Für kurze Zeit können Anfragen 403 mit API_SUBSCRIPTION_INACTIVE oder 503 mit API_ADMISSION_UNAVAILABLE zurückgeben. Klicken Sie auf der Einstellungsseite API auf Aktualisieren, warten Sie eine Minute und versuchen Sie es erneut.
Anfragen aus einem Framework oder einer Bibliothek geben 400 mit API_REQUEST_UNBOUNDED zurück? Viele Frameworks fügen jeder Anfrage standardmäßig Parameter hinzu. DeepMask akzeptiert die Sampling-Optionen temperature, top_p, presence_penalty, frequency_penalty, seed und stop innerhalb ihrer Wertebereiche sowie n nur mit dem Wert 1. Manche Modelle ignorieren einige davon. Siehe Sampling-Optionen und Optionen, die manche Modelle ignorieren. Andere Felder wie response_format, reasoning_effort und logprobs lehnt DeepMask ab, auch wenn sie null oder false sind. Auch ein leeres tools-Array lehnt DeepMask ab. Konfigurieren Sie den Client so, dass er diese Felder weglässt. Siehe Nicht unterstützte Parameter.
Sie erhalten häufig 429-Fehler mit API_CONCURRENCY_LIMIT? Ihre Anwendung führt mehr Anfragen parallel aus, als das Limit Gleichzeitige Anfragen Ihrer Organisation erlaubt. Alle Schlüssel teilen sich dieses Limit. Prüfen Sie daher, ob andere Anwendungen die Schlüssel Ihrer Organisation nutzen. Bei großen Anfragen, etwa Anfragen mit Bildern, kann ein einzelner Schlüssel auch sein Limit von 64 MiB für Anfragetexte in Bearbeitung erreichen. Reduzieren Sie die Parallelität, wie unter Parallele Anfragen in Ihrer Anwendung begrenzen gezeigt. Wie Sie ein höheres Limit anfordern, erfahren Sie unter Höhere Limits anfordern.
Anfragen mit Bildern geben 400 zurück? Prüfen Sie bei API_IMAGE_INVALID, ob das Base64 in einer einzigen Zeile steht. Verwenden Sie unter Linux base64 -w 0. Prüfen Sie außerdem, ob das Bild eine PNG-, JPEG-, GIF- oder WebP-Datei ist, ob der Typ in der Data-URL dem tatsächlichen Format der Datei entspricht und ob detail weggelassen oder auf "auto" oder "low" gesetzt ist. Senden Sie das Bild bei API_IMAGE_URL_UNSUPPORTED als Base64-Data-URL statt als Link. Verwenden Sie bei API_IMAGE_INPUT_UNSUPPORTED ein Modell mit Bildeingabe, etwa gpt-4o, und senden Sie Bilder in Benutzernachrichten. Siehe Bildeingabe und Bilddaten.
Ein Modell gibt API_MODEL_CAPACITY zurück, während andere funktionieren? Dieses Modell ist über alle Organisationen hinweg ausgelastet. Wiederholen Sie die Anfrage mit Backoff oder wechseln Sie zu einem anderen Modell, das Ihr Schlüssel nutzen darf. Siehe Modellkapazität.
Alle Schlüssel geben plötzlich 503 zurück? Ein Administrator prüft, ob die Einstellungsseite API einen Hinweis zeigt. Steht dort, dass Anfragen pausiert sind, während die letzte Nutzung geprüft wird, prüft DeepMask gerade eine Anfrage oder erfasste Nutzung. Eine Pause kann auf mehr als 20 502- oder 504-Fehler oder abgebrochene Streams innerhalb von 24 Stunden folgen. Wiederholen Sie Anfragen nicht in einer Schleife. Bleibt der Hinweis länger als einige Minuten bestehen, wenden Sie sich an den Support. Siehe Wann Anfragen pausiert werden.
Verwandte Seiten
Chat Completions
Anfrageformat, akzeptierte Felder, Bildeingabe, Streaming und Tool-Aufrufe.
Limits und faire Nutzung
Raten-, Token- und Budgetlimits und wie Sie höhere Limits anfordern.
Ausgabenlimits
Begrenzen Sie die monatlichen Ausgaben Ihrer Organisation und jedes einzelnen Schlüssels.
Nutzung und Protokolle
Sehen Sie Ihre API-Limits ein, prüfen Sie Anfragen und exportieren Sie eine CSV-Datei.
API-Schlüssel
Erstellen, prüfen und widerrufen Sie Schlüssel und legen Sie ihre Modelle fest.