Fehler & Ratenlimits

Fehler kommen als JSON im OpenAI-Fehlerformat zurück. Die Nachricht gibt an, was passiert ist, code ist ein stabiler, maschinenlesbarer Bezeichner, und jeder Nachricht wird eine Request-ID angehängt:

{
  "error": {
    "message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

Gib immer die Request-ID an, wenn du den Support kontaktierst oder ein Discord-Ticket öffnest. Damit können wir deine genaue Anfrage in den Logs finden.

Die Statuscodes, denen du tatsächlich begegnen wirst:

Zwei sehr unterschiedliche Situationen teilen sich den Status 503. Die erste ist eine vorübergehende Überlastung:

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "get_channel_failed"
  }
}

Der Code get_channel_failed (alle Anbieter ausgelastet) bedeutet, dass jeder kostenlose Anbieter für dieses Modell momentan ratenlimitiert ist. Das erholt sich innerhalb von Minuten automatisch: erneut versuchen oder Modell wechseln. Der Code model_not_found (hier nicht angeboten) bedeutet, dass der Modellname selbst sich nicht auflösen lässt, und ein erneuter Versuch wird niemals helfen. Prüfe auf Tippfehler oder schlage den aktuellen Namen im Katalog nach.

Behandle 503 mit get_channel_failed als Wiederholung/Fallback und 503 mit model_not_found als harten Fehler in deinem Client.

Ein 429 kann aus mehreren Schichten stammen:

• Unsere Obergrenze für kostenlose Modelle: 1 Anfrage pro Minute pro kostenlosem Modell pro Nutzer. Eine Fairness-Obergrenze, damit geteilte Pools die Stoßzeiten überstehen.
• Limits des Upstream-Anbieters: der Anbieter hinter einem kostenlosen Modell hat sein eigenes Limit erreicht ("temporarily rate-limited upstream", also vorübergehend upstream ratenlimitiert).
• Tägliche Token-Budgets bei einigen kostenlosen Pools; diese werden um Mitternacht UTC zurückgesetzt.
• Token-pro-Minute-Obergrenzen, die bei sehr großen Prompts auslösen.
• Ein Nebenläufigkeitslimit pro Nutzer, wenn zu viele Anfragen parallel laufen.

Kostenpflichtige Modelle haben keine von UnoRouter auferlegten Ratenlimits.

Wenn unsere Obergrenze von 1 pro Minute auslöst, erhältst du standardmäßige Ratenlimit-Header, sodass Clients präzise zurückweichen können:

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After ist dynamisch: die tatsächlich verbleibenden Sekunden in deinem Fenster, nicht pauschal 60. Die Fehlermeldung nennt auch den kostenpflichtigen Zwilling des Modells, der kein Limit hat.

Einige normalerweise kostenpflichtige Modelle werden kostenlos mit einer Obergrenze für die Anfragegröße angeboten. Zu große Prompts erhalten 413 mit einer Nachricht wie: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

Die Obergrenze gilt nur für die kostenlose Testroute; das kostenpflichtige Modell nimmt Prompts in voller Länge an.

Beachte Retry-After bei 429. Versuche 503 get_channel_failed nach kurzer Wartezeit erneut oder weiche auf ein anderes Modell aus. Wiederhole keine Fehler der 400er-Klasse, sie sind deterministisch.

Fehlgeschlagene und abgelehnte Anfragen werden nicht abgerechnet: jede Vorabreservierung auf deinem Guthaben wird erstattet, wenn die Anfrage fehlschlägt.