429 den Fehlercode und reason, um zu erkennen, welches Limit die Anfrage gestoppt hat, und warte dann Retry-After ab oder ändere das Limit. Routing und Fallbacks verringern Anbieterfehler, aber eine Anfrage kann trotzdem von einem Anbieter oder durch eine Workspace- oder Schlüsselrichtlinie gedrosselt werden.
Alle diese Fälle geben
429 zurück. Ist die Kontingentdurchsetzung des Gateways kurzzeitig nicht verfügbar, gibt das Gateway stattdessen 503 mit Hinweisen zur Wiederholung zurück.
Gateway-Limits
Jeder Benutzer hat in jedem Workspace ein Kontingent an Anfragen pro Minute, gemessen über eine gleitende Minute. API-Schlüssel, die derselbe Benutzer erstellt hat, teilen es sich. OAuth-Anfragen zählen für den angemeldeten Benutzer, und Schlüssel ohne Besitzer teilen sich ein Workspace-Kontingent. Das Kontingent steigt automatisch, sobald sich der Workspace etabliert. Ein Workspace erhält die höchste Zeile, für die er sich qualifiziert, und Änderungen werden innerhalb weniger Minuten wirksam:
Für kostenlose Modelle gilt standardmäßig außerdem ein Kontingent von 1.500 Anfragen pro UTC-Tag. Es gilt gemeinsam für alle kostenlosen Modelle und für jeden Workspace, in dem derselbe Benutzer Anfragen sendet. Anfragen an kostenpflichtige Modelle verbrauchen es nicht. Eine zugelassene kostenlose Anfrage zählt auch dann, wenn der Anbieter danach ausfällt, und Anbieter-Fallbacks innerhalb einer Anfrage zählen einmal.
Beide Limits gelten über alle Gateway-Regionen hinweg und können für einen bestimmten Benutzer und Workspace erhöht werden. Dateioperationen und Statusabfragen für Jobs verbrauchen das Minutenkontingent; Verwaltungs-Endpunkte nicht.
Eine abgelehnte Anfrage gibt
429 mit Retry-After in Sekunden zurück. Warte so lange, bevor du es erneut versuchst.
Limits der Verwaltungs-API
Verwaltungs-Endpunkte wie/v1/keys, /v1/logs und /v1/analytics teilen sich ein Kontingent von 200 Einheiten pro Minute je Zugangsdaten. Jeder Verwaltungsschlüssel, jedes OAuth-Token und jede Dashboard-Sitzung hat ein eigenes Kontingent; Anfragen ohne Zugangsdaten teilen sich eines pro IP-Adresse. Modell-, Datei-, Batch- und Job-Endpunkte verbrauchen es nicht.
Jede Anfrage verbraucht Einheiten danach, wie viel Arbeit sie verursacht:
/v1/health und CORS-Preflight-Anfragen sind kostenlos. Eine Anfrage über dem Kontingent gibt 429 mit rate_limit_exceeded, dem Grund management_api_rate_limit und Retry-After: 60 zurück. Die Zählung ist ein Näherungswert, und diese Antworten enthalten keine x-ratelimit-*-Header. Verteile Massen-Skripte daher zeitlich, statt sie bis an das Limit laufen zu lassen.
Schlüssellimits und Budgets
Die täglichen, wöchentlichen oder monatlichen Anfrage- und Ausgabenlimits eines API-Schlüssels sowie die Budgets des Workspace geben nach dem Erreichen429 mit key_limit_exceeded zurück. reason, limit_window und reset_at im Body nennen das Limit und den Zeitpunkt, zu dem sein Zeitraum zurückgesetzt wird, und Retry-After gibt die Sekunden bis dahin an.
Retry-After fehlt, wenn sich das Limit nicht von selbst zurücksetzt, etwa bei einem Gesamtbudget oder einem weich gesperrten Schlüssel. Versuche es nicht erneut: Erhöhe das Workspace-Budget, erhöhe das Limit des Schlüssels oder verwende einen anderen Schlüssel.
Owner und Admins eines Workspace verwalten Budgets mit einem Management-Schlüssel über /v1/budgets oder unter Einstellungen → Budgets. Dort siehst du für jedes Budget die bisherigen Ausgaben, den genutzten Anteil, eine Hochrechnung für den Zeitraum und den Zeitpunkt des Zurücksetzens. Tages-, Wochen- und Monatsbudgets werden an UTC-Grenzen zurückgesetzt: um Mitternacht, montags um 00:00 und am 1. des Monats.
Ausgabenwarnungen können warnen, bevor diese Limits erreicht sind. Eine sperrende Ausgabenregel gibt 429 mit spend_rule_blocked zurück. Sie arbeitet nach bestem Bemühen und greift erst einige Minuten, nachdem die Ausgaben ihr Limit überschritten haben. Für exakte Obergrenzen verwende daher Schlüssellimits und Budgets. Ein x-phaseo-spend-warning-Header bedeutet, dass eine Sperre folgen kann.
Abteilungsbudgets
Owner und Admins verwalten Abteilungsbudgets mitphaseo department-budgets, der API /v1/department-budgets, unter Einstellungen → Budgets oder mit der Ressource phaseo_department_budget des Terraform-Providers. Die Ausgaben einer Abteilung umfassen dieselben Schlüssel und OAuth-Anfragen wie Ratenlimits für Abteilungen.
Hat eine Abteilung ihr tägliches, wöchentliches oder monatliches Budget aufgebraucht, geben API-Schlüssel-Anfragen, die ihr zugerechnet werden, 429 mit key_limit_exceeded und dem Grund department_daily_cost_budget_reached, department_weekly_cost_budget_reached oder department_monthly_cost_budget_reached zurück. department_id und department_name im Body nennen die Abteilung, und reset_at und Retry-After geben an, wann ihr Budget zurückgesetzt wird.
- Ist die Budgetprüfung kurzzeitig nicht verfügbar, werden Anfragen zugelassen, sodass eine Abteilung ihr Budget für kurze Zeit überschreiten kann.
- Owner und Admins erhalten eine mobile Push-Benachrichtigung bei etwa 80 % und erneut bei 100 % eines Budgets. Für diese Warnungen werden die Budgets alle 15 Minuten geprüft, daher können Anfragen schon abgelehnt werden, bevor die 100-%-Warnung eintrifft.
Ratenlimit-Richtlinien
Workspace-Admins können benannte Richtlinien erstellen, dierequests_per_minute, tokens_per_minute und concurrent_requests festlegen, und sie Schlüsseln, Mitgliedern, Abteilungen oder Endnutzern zuweisen. Verwalte sie mit phaseo rate-limits policies und phaseo rate-limits assignments, der API /v1/rate-limits, unter Einstellungen → Ratenlimits oder mit den Ressourcen phaseo_rate_limit_policy und phaseo_rate_limit_assignment des Terraform-Providers.
Was einer Abteilung zugerechnet wird. Ein mit einer Abteilung verknüpfter Schlüssel zählt nur für diese Abteilung. Jeder andere Schlüssel zählt für alle Abteilungen, denen die Person angehört, die ihn erstellt hat, und OAuth-Anfragen zählen für alle Abteilungen ihres Nutzers. Ein Mitglied mit einer Abteilungsüberschreibung zählt nur für die Abteilung der Überschreibung. Damit diese Schlüssel und OAuth-Anfragen nur für die Hauptabteilung der Person zählen, setze die Abteilungszuordnung auf primary: unter Einstellungen → Benachrichtigungen oder mit
spend.department_attribution in PATCH /v1/notifications/settings und einem Management-Schlüssel. Abteilungsbudgets und Ausgabenregeln verwenden dieselbe Einstellung.
Gelten mehrere Richtlinien, wird jede gezählt, und die erste ausgeschöpfte lehnt die Anfrage ab. Richtlinien gelten zusätzlich zu den Gateway-Limits. Änderungen an Richtlinien werden innerhalb von etwa einer Minute wirksam; Änderungen an Abteilungsmitgliedschaften im Dashboard oder über SCIM können bis zu etwa fünf Minuten dauern.
Anfragen und Tokens pro Minute
Beide werden über eine gleitende Minute gemessen.tokens_per_minute zählt die Eingabe- und Ausgabe-Tokens jeder Anfrage, sobald sie abgeschlossen ist, auch bei gestreamten und fehlgeschlagenen Anfragen, die Tokens verbraucht haben. Eine Anfrage wird abgelehnt, sobald der Verbrauch in der letzten Minute das Limit erreicht; bereits laufende Anfragen können den Verbrauch daher darüber hinaus bringen. Anbieter-Fallbacks innerhalb einer Anfrage zählen einmal.
Eine abgelehnte Anfrage gibt 429 mit rate_limit_exceeded, dem Grund policy_requests_per_minute oder policy_tokens_per_minute, der policy_id, dem limit_scope (key, member, department, workspace oder end_user) und Retry-After in Sekunden zurück.
Antworten auf Anfragen, für die eine Richtlinie gilt, enthalten die Header des strengsten Limits:
Eine abgelehnte Anfrage enthält nur die Header des Limits, das sie abgelehnt hat. Gezählt wird im Hintergrund, daher ist
remaining ein Näherungswert, und die Token-Header enthalten den Verbrauch der aktuellen Anfrage noch nicht.
Gleichzeitige Anfragen
concurrent_requests begrenzt, wie viele Anfragen gleichzeitig laufen können. Eine Anfrage belegt einen Platz ab ihrer Zulassung, bis ihre Antwort vollständig gesendet ist, bei gestreamten Antworten also den ganzen Stream lang; Anbieter- und Modell-Fallbacks innerhalb der Anfrage teilen sich diesen Platz. Sind alle Plätze belegt, wird die Anfrage mit dem Grund policy_concurrent_requests und Retry-After: 1 abgelehnt.
Die Prüfung eines Gleichzeitigkeitslimits wartet auf den Zähler der Richtlinie, was etwas Latenz hinzufügt. Ein Platz, dessen Freigabe verloren geht, wird nach 15 Minuten von selbst frei. Batches und Echtzeitsitzungen werden nicht begrenzt, und eine Videogenerierung belegt nur während der Anfrage, die sie startet, einen Platz.
Strenge Richtlinien
Standardmäßig ist eine Richtlinie offen im Fehlerfall: Können ihre Limits nicht geprüft werden, wird die Anfrage zugelassen. Setzefail_closed, um sie streng zu machen. Eine strenge Richtlinie prüft Anfrage- und Token-Limits, bevor die Anfrage gesendet wird, statt im Hintergrund. Das macht sie exakt, erhöht aber die Latenz. Können sie nicht innerhalb von zwei Sekunden geprüft werden, wird die Anfrage mit dem Grund policy_unavailable abgelehnt.
Ablehnungen wegen Gleichzeitigkeit und policy_unavailable enthalten keine x-ratelimit-*-Header.
Anbieterlimits
BYOK-Anfragen verwenden die Limits deines Anbieterkontos. Verwaltete Anfragen nutzen gemeinsame Anbieterkapazität, die kein Kontingent für deinen Workspace ist. Phaseo leitet einen validiertenRetry-After-Wert weiter, wenn der Anbieter einen sendet. BYOK-Antworten können außerdem X-Phaseo-Upstream-RateLimit-*-Header enthalten; verwaltete Anfragen lassen sie weg, weil sie gemeinsame Kapazität beschreiben. Andere Upstream-Header werden nicht weitergeleitet. Die 429-Codes der Anbieter findest du unter Fehlercodes.
Eine gedrosselte Anfrage behandeln
- Lies den Fehlercode, um vorübergehende Drosselung von einem Limit, Budget oder einer Richtlinie zu unterscheiden, die eine Konfigurationsänderung erfordert.
- Beachte
Retry-After, falls vorhanden. Der Wert kann Sekunden oder ein HTTP-Datum sein; validiere ihn, bevor du einen erneuten Versuch planst. - Verwende andernfalls exponentielles Backoff mit Jitter und einer maximalen Wartezeit.
- Begrenze Wiederholungen durch eine maximale Anzahl an Versuchen und eine Gesamtfrist. Brich aufgegebene Arbeit ab und gib jeden fehlgeschlagenen Antwort-Body frei, bevor du es erneut versuchst.
- Reduziere die Parallelität, wenn die Drosselung anhält.
429-Raten nach Endpunkt und Modell und prüfe die Fallback-Häufigkeit in den Anfrageprotokollen. Vergleiche sie mit deinen Routing-Einstellungen und, bei BYOK-Traffic, mit den Kontingenten deines Anbieterkontos. Guardrails steuern, welche Schlüssel welche Modelle und Anbieter nutzen können.