Rate Limits

Jeder API-Token hat sein eigenes Rate Limit, ausgedrückt in Requests pro Minute, angewendet pro Token (nicht pro IP, nicht pro Team). Der plattformseitige Standardwert für einen frisch erstellten Token beträgt 60/Min.

#Limit konfigurieren

Der Eigentümer des Tokens setzt das Limit in der Oberfläche API-Tokens unter den Team-Einstellungen. Das Formular enthält ein numerisches Eingabefeld "Rate Limit (Requests pro Minute)" mit folgenden Regeln:

Untergrenze: 30 Req./Min. Das Formular weist alles unter 30 zurück. Der Server klemmt jeden Wert unter 30 zur Request-Zeit auf 30, sodass eine veraltete oder von Hand bearbeitete Zeile die Untergrenze nicht umgehen kann.
Keine Obergrenze in der UI — Eigentümer können so hoch drehen, wie sie es benötigen. Wenn Sie mehr als ein paar Hundert pro Minute brauchen, sprechen Sie zuerst mit dem Vorgio-Support; dauerhafte Burst-Kapazität erfordert möglicherweise Infrastruktur-Tuning.

Die Liste der ausgegebenen Tokens zeigt das Pro-Minute-Limit jedes Tokens neben seinem Namen und dem Zeitstempel der letzten Verwendung.

#Warum die Untergrenze existiert

Ein zu niedrig konfiguriertes Limit zerstört stillschweigend die eigene Integration eines Teams. Wenn Ihr Shop auch nur einen moderaten Checkout-Burst hat (ein Flash-Sale, eine Marketing-E-Mail, die um 09:00 Uhr versendet wird), wird ein Token mit 1/Min. innerhalb von Sekunden 429er auswerfen. Die Untergrenze von 30/Min. entspricht einem Request alle zwei Sekunden — komfortabel über jeder vernünftigen Checkout-Rate und niedrig genug, um keinen Plattform-Spielraum auf untergenutzte Tokens zu verschwenden.

#Die `429`-Response

Wenn Sie das Limit überschreiten, gibt Vorgio 429 Too Many Requests mit dem standardmäßigen RFC 7807 Envelope zurück:

 1HTTP/1.1 429 Too Many Requests
 2Retry-After: 17
 3Content-Type: application/problem+json
 4
 5{
 6  "type": "https://accounting.example/problems/too-many-requests",
 7  "title": "Too Many Requests",
 8  "status": 429,
 9  "detail": "Rate limit exceeded. Try again in 17 seconds."
10}

Der Retry-After-Header sagt Ihnen, wie viele Sekunden vergehen, bis Ihr nächster Request zugelassen wird. Halten Sie sich immer daran — ein früherer Wiederholungsversuch verlängert nur das Drosselungsfenster.

#Empfohlener clientseitiger Back-off

Für den synchronen POST /v1/checkouts-Pfad (bei dem ein Kunde an einem Checkout-Button wartet):

 1function vorgioCallWithRetry(callable $do, int $maxAttempts = 3) {
 2    for ($i = 0; $i < $maxAttempts; $i++) {
 3        try {
 4            return $do();
 5        } catch (RateLimitedException $e) {
 6            if ($i === $maxAttempts - 1) throw $e;
 7            sleep(min($e->retryAfter, 5));   // cap to 5s — customer is waiting
 8        }
 9    }
10}

Für Batch-/Async-Pfade (z. B. nächtlicher Import eines Auftragsrückstaus) können Sie den vollen Retry-After-Wert abwarten und dann fortfahren.

#Pro Token, nicht pro Team

Jeder Token hat seinen eigenen Bucket. Wenn Sie separate Tokens für separate Umgebungen (empfohlen) oder für separate Workloads ausstellen (z. B. einen für Checkouts, einen für Cron-gesteuerte Mark-Paid-Synchronisation), konkurrieren diese nicht miteinander.

 1Vorgio team
 2├── token "wp-prod"    — 120/min, used by checkout flow
 3├── token "wp-cron"    — 30/min, used by nightly mark-paid sync
 4└── token "wp-staging" — 30/min, on a totally separate WP install

Der Checkout-Flow-Token kann seinen Bucket erschöpfen, ohne den nächtlichen Cron zu blockieren, und umgekehrt.

#Was ist mit Webhooks, die Vorgio an Sie sendet?

Webhooks unterliegen von Ihrer Seite aus keinem Rate Limit — Vorgio respektiert einfach das, was Ihr Endpoint verarbeiten kann, gemäß dem dokumentierten Retry-Schema (siehe Webhooks). Wenn Ihr Endpoint nicht hinterherkommt, geben Sie schnell 2xx zurück und verarbeiten Sie asynchron. Versuchen Sie nicht, "Vorgio zu drosseln", indem Sie langsam antworten — langsame Antworten zählen als Fehler und lösen Wiederholungsversuche aus.