Fehler & Ratenbegrenzungen
Formate von Fehlerantworten, die vollständige Tabelle der HTTP-Statuscodes, das Verhalten von Ratenbegrenzungen und eine Retry-Strategie, die mit Atlas Cloud funktioniert.
Formate von Fehlerantworten
Atlas Cloud liefert drei verschiedene Fehlerformate, je nachdem, welchen Teil der API Sie aufrufen. Prüfen Sie das Format, bevor Sie einen Parser schreiben.
Wird von den LLM-Protokoll-Endpunkten und den Endpunkten zur Mediengenerierung verwendet:
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Jede Antwort enthält einen X-Request-ID-Header. Protokollieren Sie ihn — er ist der schnellste Weg für den Support, einen bestimmten Aufruf nachzuverfolgen.
HTTP-Statuscodes
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
400 | Fehlerhafte Anfrage: nicht parsbarer Body, fehlendes model, falscher Content-Type, ungültiger Retention-Header oder eine ungültige webhook_url | Korrigieren Sie die Anfrage. Das Feld msg benennt das konkrete Problem |
401 | Authentifizierung fehlgeschlagen — Schlüssel fehlt, ist unbekannt oder abgelaufen | Prüfen Sie den Schlüssel. Beachten Sie: Auch ein falscher URL-Pfad liefert 401, prüfen Sie also ebenfalls den Endpunkt |
402 | Unzureichendes Guthaben oder ein aufgebrauchtes Coding-Plan-Kontingent | Aufladen |
403 | Konto oder Benutzer ist nicht berechtigt — dazu gehört die Verwendung eines Coding-Plan-Schlüssels bei einem Modell, das ihn nicht akzeptiert | Prüfen Sie den Geltungsbereich des Schlüssels oder kontaktieren Sie den Support |
404 | Ressource nicht gefunden. Bei Modellen betrifft dies auch Modelle, die für Ihr Konto nicht verfügbar sind | Prüfen Sie die Modell-ID gegen den Katalog |
413 | Anfrage-Body überschreitet 50 MB | Senden Sie eine URL statt Inline-Base64 oder laden Sie die Datei vorher hoch |
429 | Ratenbegrenzung erreicht | Backoff und erneut versuchen — siehe unten |
451 | In Ihrer Region gesperrt | Nicht wiederholbar |
500 | Interner Fehler | Einmal wiederholen, dann mit der Request-ID melden |
503 | Vorübergehend nicht verfügbar | Mit Backoff wiederholen |
504 | Eine synchrone Anfrage hat die maximale Wartezeit überschritten | Auf den asynchronen Ablauf umsteigen und pollen |
Ein 401 bedeutet nicht immer, dass Ihr Schlüssel falsch ist. Das Gateway authentifiziert vor dem Routing, daher erzeugt auch ein Tippfehler im Pfad ein 401 statt eines 404. Wenn ein Schlüssel anderswo funktioniert, prüfen Sie zuerst die URL.
Fehlercodes auf Aufgabenebene
Wenn eine asynchrone Aufgabe fehlschlägt, enthält data.error_code einen numerischen Plattformcode, der genauer ist als der HTTP-Status. 1039 zeigt beispielsweise an, dass die Eingabe von der Inhaltsmoderation abgelehnt wurde.
data.error enthält eine für Menschen lesbare Beschreibung. Protokollieren Sie beides zusammen mit der Vorhersage-ID.
Ratenbegrenzungen
Ratenbegrenzungen gelten pro Konto und pro Modell. Wird eine überschritten, folgt 429.
LLM- und Medien-Endpunkte liefern keine Header X-RateLimit-Limit, X-RateLimit-Remaining oder Retry-After. Sie können Ihr verbleibendes Kontingent nicht aus den Antwort-Headern ablesen — implementieren Sie stattdessen Backoff auf dem Client.
Die Abrechnungs-Endpunkte unter /public/v1 sind die Ausnahme: Ihre 429-Antworten enthalten Retry-After.
Wenn Sie für eine Produktionslast höhere Limits benötigen, kontaktieren Sie uns mit Ihrem erwarteten Anfragevolumen und Modell-Mix.
Retry-Strategie
Wiederholen Sie bei 429, 500, 503 und 504 sowie bei Netzwerkfehlern. Wiederholen Sie nicht bei 400, 401, 402, 403, 404 oder 451 — sie scheitern identisch.
Lesende Anfragen können Sie unbesorgt wiederholen. Vorsicht beim Wiederholen von Generierungs-Einreichungen: Eine Anfrage, die in ein Timeout gelaufen ist, kann dennoch angenommen worden sein, und ein blinder Retry kann eine zweite Aufgabe erzeugen — und abrechnen. Reichen Sie besser asynchron ein und pollen Sie, dann bedeutet eine verlorene Antwort nie eine verlorene Aufgabe.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Exponentielles Backoff + Jitter, damit nicht alle Clients gleichzeitig erneut versuchen
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseFehler beim Streaming
Wenn eine Streaming-Anfrage vor dem Öffnen des Streams scheitert, erhalten Sie einen normalen HTTP-Fehler. Sobald der Stream gestartet ist, bleibt die Verbindung offen und der Fehler kommt als Ereignis im Stream an — ein 200 bei einem Streaming-Aufruf garantiert also keine vollständige Antwort. Behandeln Sie einen Abbruch mitten im Stream immer.
Streams können außerdem SSE-Kommentarzeilen enthalten, die mit : beginnen und als Keep-Alive-Signale dienen. Diese sind keine Daten und müssen ignoriert werden — die meisten SSE-Clients erledigen das für Sie, selbst geschriebene Parser oft nicht.
Hilfe erhalten
Wenn Sie ein Problem melden, geben Sie Folgendes an:
- Den
X-Request-ID-Header aus der fehlerhaften Antwort - Die Vorhersage-ID bei asynchronen Aufgaben
- Die exakte Modell-ID und den Zeitstempel
Sie erreichen uns über den Support.
Verwandte Themen
Last updated on