Fehler
HTTP-Statuscodes, Fehlerformat und welche Fehler du wiederholen solltest.
Fehlerformat
Fehler kommen als JSON mit einem HTTP-Statuscode ungleich 2xx:
{
"error": {
"message": "key not allowed to access model. This key can only access models=['mistral-small-24b']. Tried to access gemma-4-31b",
"type": "key_model_access_denied",
"param": "model",
"code": "403"
}
}Werte message nur zur Anzeige und Fehlersuche aus – der Text kann sich ändern. Für die Programmlogik zählt der HTTP-Status. Die OpenAI-SDKs werfen passende Exceptions (z. B. openai.RateLimitError bei 429).
Einige Fehler (403 für nicht unterstützte Pfade, 413, 503 beim IP-Limit) kommen direkt von unserem Gateway und haben eine HTML-Seite statt JSON als Body.
Statuscodes
| Status | Bedeutung | Typische Ursache | Wiederholen? |
|---|---|---|---|
400 | ungültiger Request | Kontextfenster überschritten, unbekanntes Modell, ungültiger Parameter, Bild als URL statt Data-URI | nein |
401 | nicht authentifiziert | Key fehlt, falsch, widerrufen, abgelaufen oder wegen seines Credit-Limits bzw. des Nutzerlimits gesperrt | nein |
403 | nicht erlaubt | Account hat kein aktives Paket (no_package); Key oder Nutzer darf dieses Modell nicht nutzen; nicht unterstützter Endpunkt | nein |
413 | Request zu groß | Body größer als 20 MB, meist wegen großer Bilder | nein |
429 | Paket verbraucht | Credits des Abrechnungszeitraums aufgebraucht (insufficient_quota) | nein, erst nach Upgrade oder im nächsten Zeitraum |
429 | Rate-Limit | Requests pro Minute oder parallele Requests deines Pakets erreicht, gilt für den ganzen Account (rate_limit_exceeded) | ja, nach retry-after bzw. wenn laufende Requests fertig sind |
500 | interner Fehler | unerwarteter Fehler | ja, mit Backoff |
503 | vorübergehend nicht verfügbar | Modell wird gewechselt oder gewartet; zu viele Requests von deiner IP-Adresse | ja, mit Backoff |
Wie du Retries einbaust, steht unter Wartezeiten und Retries.
Paket verbraucht
Sind die Credits deines Pakets für den laufenden Abrechnungszeitraum aufgebraucht, antwortet die API mit 429 und diesem Body:
{
"error": {
"message": "The credits of your package for the current billing period are used up. Upgrade your package in the portal to continue right away: https://app.promodelhub.de",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_quota"
}
}Das ist kein normales Rate-Limit: Ein Retry hilft nicht. Die Sperre gilt, bis der nächste Abrechnungszeitraum beginnt oder der Owner ein größeres Paket bucht – dann ist die API sofort wieder frei (Abrechnung). Ein bereits laufender Request wird nicht abgebrochen.
Die OpenAI-SDKs werfen für beide Fälle RateLimitError. Ein Rate-Limit wiederholen sie vorher automatisch (standardmäßig zweimal), insufficient_quota nicht: Die API schickt dabei x-should-retry: false, die Exception kommt sofort. Unterscheide die Fälle am Fehlercode:
import time
import openai
try:
response = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Hallo!"}],
)
except openai.RateLimitError as e:
if e.code == "insufficient_quota":
# Paket verbraucht: nicht wiederholen, Job anhalten und Bescheid geben
raise
# Rate-Limit: warten, dann erneut senden
time.sleep(int(e.response.headers.get("retry-after", "5")))Den Fehlercode findest du auch im Body unter error.code (in Python e.body["code"]).
Häufige Fehler
401 nach einiger Zeit, vorher lief alles: Der Key hat sein Credit-Limit oder das Limit des Nutzers für den laufenden Abrechnungszeitraum erreicht, ist abgelaufen oder wurde widerrufen bzw. der Nutzer gesperrt. Den Status jedes Keys siehst du im Portal unter API-Keys.
403 mit no_package: Dein Account hat kein aktives Paket – entweder wurde noch keins aktiviert oder es ist nach einer Kündigung abgelaufen. Der Owner aktiviert oder bestellt ein Paket im Portal, danach funktionieren die Keys sofort (Abrechnung).
429 mit insufficient_quota: Die Credits deines Pakets sind verbraucht, siehe Paket verbraucht.
429 mit rate_limit_exceeded: Dein Account hat das Limit für Requests pro Minute oder für parallele Requests seines Pakets erreicht. Die Limits gelten für alle Keys zusammen. Warte die Zeit aus retry-after ab bzw. bis laufende Requests fertig sind, begrenze die Parallelität in deiner Anwendung oder buche ein größeres Paket (Limits).
403 mit key_model_access_denied: Die Meldung nennt die Modelle, die der Key nutzen darf. Prüfe die API-ID auf Tippfehler und die Modellbeschränkung von Key und Nutzer.
400 mit ContextWindowExceededError: Eingabe plus max_tokens sind größer als das Kontextfenster des Modells. Kürze den Verlauf oder setze max_tokens kleiner (Limits).
Leere Antwort mit finish_reason: "length": max_tokens war schon aufgebraucht, bevor die eigentliche Antwort begann – meist wegen eingeschaltetem Reasoning. Erhöhe max_tokens.