Rate Limits
Per-Tier-API-Caps, Header, Retry-Policy und wo man den Live-Remaining-Count liest.
Rate-Limiting ist per Org und am Gateway angewandt. Drei Hebelpunkte: Requests pro Minute, Requests pro Tag und Per-Endpoint-Spezialisierung (z. B. Generation ist stärker constraint als Reads).
Per-Tier-Defaults
| Tier | Req/min | Req/Tag | Concurrent Generations |
|---|---|---|---|
| Free | 60 | 5.000 | 1 |
| Pro | 600 | 50.000 | 5 |
| Team | 3.000 | 250.000 | 25 |
| Enterprise | custom | custom | custom |
Generation-Endpoints (POST /v1/personas,
POST /v1/personas/{id}/refine, POST /v1/personas/{id}/fork)
verbrennen separat vom Per-Minute-Cap aus dem Concurrent-Generations-
Budget. Reads (GET *) nicht.
Header
Jede Response trägt:
X-RateLimit-Limit: <Per-Minute-Cap>
X-RateLimit-Remaining: <Verbleibend im aktuellen Fenster>
X-RateLimit-Reset: <Unix-Timestamp, wenn Fenster zurücksetzt>
Bei 429 zusätzlich:
Retry-After: 12
(Sekunden, bis der nächste Request erlaubt ist)
Endpoint-spezifische Caps
Manche Endpoints haben engere individuelle Budgets, um Upstream-LLM- Provider zu schützen:
| Endpoint-Familie | Pro-Cap |
|---|---|
POST /v1/personas (Generation) | 60/Stunde, 5 concurrent |
POST /v1/personas/{id}/refine | 120/Stunde |
POST /v1/chat/sessions/{id}/messages | 600/min (zählt gegen den allgemeinen Cap) |
POST /v1/personas/{id}/audit | 300/Stunde |
Cap-Multiplikatoren pro Tier: Free × 0.1, Pro × 1, Team × 5, Enterprise custom.
Client-seitige Backpressure
Warte nicht auf 429. Die SDKs lesen X-RateLimit-Remaining nach
jedem Call; wenn du unter 10 % des Caps mit > 30 Sekunden bis Reset
bist, slow down. Das SDK belichtet einen Callback für Custom-
Backpressure:
const client = new Moonborn({
apiKey: process.env.MOONBORN_API_KEY,
onRateLimitNearCap: ({ remaining, resetIn }) => {
if (remaining < 50) setMyOwnBackpressure(resetIn);
},
});Quota vs Rate-Limit
Das ist unterschiedlich. Rate-Limit ist per-Minute / per-Tag geformt,
um Durchsatz zu schützen. Quota ist ein tier-gebundener
Monats-Cap auf bestimmte Operationen (z. B. „100 Generations/Monat
auf Pro"). Ein Quota-Cap gibt quota_exceeded (429) zurück; das
Rate-Limit gibt rate_limited (429) zurück. Selber Status,
unterschiedlicher code im Envelope.
Enterprise
Per-Org-Custom-Caps via Vertrag. Konfigurierbar via
api.rate_limit.*-Config-Items (Owner-Rolle, nur Enterprise).
Ehrlicher Scope
Rate-Limits schützen das System; sie formen nicht die UX deiner Anwendung. Buffer, Queue und Retry in deinem Code; behandle 429 als routine, nicht als außergewöhnlich.