Ratenlimits & Fehler
Die Grenzen und die Bedeutung jedes Statuscodes.
Ein 429 kann aus mehreren Schichten stammen:
- Unser Deckel für kostenlose Modelle: 1 Anfrage pro Minute, je kostenlosem Modell, je Nutzer.
- Upstream-Grenzen: der Anbieter hinter einem kostenlosen Modell hat seinen eigenen Deckel erreicht.
- Tägliche Token-Budgets bei manchen kostenlosen Pools, Zurücksetzung um Mitternacht UTC.
- Deckel für Token pro Minute, ausgelöst durch sehr große Prompts.
- Eine Grenze für gleichzeitige Anfragen je Nutzer.
Kostenpflichtige Modelle haben keine von UnoRouter auferlegten Ratenlimits.
Greift der Deckel von 1 pro Minute, kommen die üblichen Rate-Limit-Header:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After nennt die im Fenster verbleibenden Sekunden, keine pauschalen 60. Die Meldung nennt das kostenpflichtige Modell, das keine Grenze hat.
Manche kostenpflichtigen Modelle werden mit einem Deckel für die Anfragegröße kostenlos angeboten. Zu große Prompts liefern 413: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
Der Deckel gilt nur für die kostenlose Route. Das kostenpflichtige Modell nimmt Prompts in voller Länge.
Fehler liefern JSON im OpenAI-Fehlerformat. code ist eine stabile Kennung. An jede Meldung wird eine Anfrage-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"
}
}Die Anfrage-ID in Supportanfragen angeben. Sie findet die Anfrage in den Protokollen.
Wenn du Key oder Base-URL noch einrichtest, beginne mit Schnellstart
Die Statuscodes, denen du tatsächlich begegnen wirst:
| Code | Bedeutung | Was zu tun ist |
|---|---|---|
400 | Ungültige Anfrage: falscher Parameter oder ein von der Moderation blockierter Prompt. | Die Anfrage korrigieren. Unverändert erneut gesendet scheitert sie wieder. |
401 | Fehlender, ungültiger, abgelaufener oder deaktivierter Schlüssel. | Den Header Authorization und die Tokens page prüfen. |
402 | Das eigene Ausgabenlimit dieses Schlüssels ist erschöpft. | Erhöhe das Limit des Schlüssels oder erstelle einen neuen Schlüssel. |
403 | Guthaben leer, Modell für diesen Schlüssel nicht erlaubt oder IP nicht auf der Freigabeliste. | Lade auf oder prüfe die Modell- und IP-Einschränkungen des Schlüssels. |
413 | Die Anfrage überschreitet den Größendeckel der kostenlosen Testnutzung des Modells. | Kürze den Prompt oder wechsle zum kostenpflichtigen Modell. |
429 | Ein Ratenlimit wurde ausgelöst (siehe die Arten unten). | Warte die Retry-After-Sekunden ab, versuche es dann erneut oder wechsle das Modell. |
500 | Auf unserer Seite oder beim Upstream-Anbieter ist etwas fehlgeschlagen. | Nach kurzer Wartezeit erneut versuchen. Anhaltende 500 melden. |
503 | Alle Anbieter ausgelastet oder der Modellname existiert nicht. | Die Meldung lesen: Auslastung löst sich in Minuten, ein Tippfehler nicht. |
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"
}
}get_channel_failed bedeutet, dass jeder kostenlose Anbieter für dieses Modell ratenbegrenzt ist. Das löst sich in Minuten: erneut versuchen oder das Modell wechseln. model_not_found bedeutet, dass der Name nicht auflösbar ist; erneutes Versuchen hilft nie. Auf Tippfehler oder den Katalog prüfen.
get_channel_failed als wiederholbar behandeln und model_not_found als harten Fehler.
Ein unter Last verschwundenes Modell kommt von selbst zurück; um sofort benachrichtigt zu werden, beobachte es in Benachrichtigungen
Pinnt dein Schlüssel Anbietergruppen, gibt es einen dritten 503, wenn nur deine gepinnten Gruppen ausgefallen sind, siehe Gruppen-Pinning
Bei 429 Retry-After beachten. 503 get_channel_failed nach kurzer Wartezeit erneut versuchen oder das Modell wechseln. Fehler der 400er-Klasse nicht wiederholen.
Fehlgeschlagene und abgelehnte Anfragen werden nie berechnet; wie Vorabbuchung und Erstattung funktionieren, steht in Konto & Abrechnung