Rate Limits

Jeder FourA API Request durchläuft drei Prüfungen, bevor er eine Engine erreicht: die Limits deines eigenen Tarifs, danach das geteilte Plattform-Kontingent für den gesamten Traffic und schließlich das geteilte Plattform-Kontingent für den aufgerufenen Endpoint. Jede Prüfung kann einen Request eigenständig ablehnen, und jede antwortet mit einem unterschiedlichen Body.

Die drei Prüfungen in Reihenfolge

  1. Tarif-Limits. Was dein eigener Tarif erlaubt: welche Endpoints und Parameter enthalten sind, wie viele Requests gleichzeitig pro Endpoint laufen dürfen, wie viele pro Minute, wie viele Browser-Requests pro Tag sowie die im Abrechnungszeitraum verfügbaren Credits und die Bandbreite.
  2. Globales Plattform-Limit. Alles, was der aufgerufene API-Host in diesem Moment verarbeitet, unabhängig davon, an welchen Endpoint der Traffic ging. Eine Ablehnung hier meldet "service": "api".
  3. Plattform-Limit pro Endpoint. Traffic auf dem aufgerufenen Single-, Proxy- oder Browser-Dienst.

Dein eigener Tarif wird zuerst geprüft, und diese Reihenfolge ist Teil des Vertrags, kein Implementierungsdetail. Die geteilten Kontingente sind Gemeinschaftsgut. Ein Request, den die Plattform ohnehin ablehnen würde, darf diese auf dem Weg zur Ablehnung nicht verbrauchen. Sendet ein Account weit mehr, als sein Tarif erlaubt, wird er gestoppt, bevor er Ressourcen berührt, die andere nutzen.

Die Prüfungen 2 und 3 zählen den gesamten Traffic von FourA, nicht deinen eigenen. Verstehe eine Ablehnung bei beiden als "FourA ist ausgelastet", nicht als "du hast zu viel gesendet". Prüfung 1 betrifft ausschließlich deinen Account, und nichts anderes auf der Plattform beeinflusst sie.

Eine Ablehnung durch eine der geteilten Prüfungen gibt deinem Account alles zurück, was beim Einlass gezählt wurde, sowohl das Kontingent pro Minute als auch den täglichen Browser-Slot, da der Request nie ein Backend erreicht hat. Sie zählt auch nicht für die Retry-Pause, die unter Requests per minute beschrieben ist: Die Kapazität von FourA hat ihn abgelehnt, nicht dein Tarif.

POST /api/auto/ belegt keinen eigenen Slot. Die Single-, Proxy- und Browser-Unteraufrufe, die es für dich ausführt, durchlaufen alle drei Prüfungen wie jeder andere Request. Ein paralleler Batch von Auto-Aufrufen wird deinem Tarif daher über seine Unteraufrufe angerechnet. (Deine Request-Zahlen und deine Erfolgsrate zählen den Auto-Aufruf selbst einmal; die Unteraufrufe werden als dessen Versuche dargestellt.)

Tarif-Limits

Ein Tarif-Limit antwortet mit einem X-FourA-Limit Header, der das Limit benennt, das den Aufruf abgelehnt hat. Derselbe Code steht im Body unter reason, sodass du darauf verzweigen kannst, ohne Header zu lesen. Jeder Body eines Tarif-Limits enthält error, reason und documentation; die restlichen Felder hängen vom jeweiligen Limit ab.

X-FourA-Limit Status Was aufgebraucht ist
plan_limit_feature 403 Der aufgerufene Endpoint oder der Parameter exitCountries, exitState, exitCity, exitAsn oder exitOs ist nicht in deinem Plan enthalten
plan_limit_premium 403 exitClass: premium ist nicht in deinem Plan enthalten, oder ein Proxy-Request nennt eine Exit Location ohne verbleibenden Premium-Traffic
plan_limit_concurrency 429 Gleichzeitige Requests auf diesem Endpoint
plan_limit_rate 429 Requests pro Minute auf diesem Endpoint
plan_limit_browser_daily 429 Browser-Requests fuer den Tag
plan_limit_credits 429 Abgerechnete Credits fuer den Abrechnungszeitraum
plan_limit_bandwidth 429 Bandbreite fuer den Abrechnungszeitraum

Die Werte hinter jedem Limit stammen aus deinem Plan. Der Reiter Limits & Features unter Usage & Limits fuehrt sie neben deiner aktuellen Nutzung auf. Hardcode sie nicht: Jede Ablehnung enthaelt das Limit, das sie ausgeloest hat.

Ein abgelehnter Request kostet nichts. Das Ergebnis ist rate_limit, und nur success wird abgerechnet.

Endpoint oder Parameter nicht im Plan enthalten

Ein 403-Fehler mit plan_limit_feature bedeutet, dass der Aufruf etwas angefordert hat, das der Plan nicht enthaelt. Die Pruefung erfolgt, bevor etwas gezaehlt wird, sodass der abgelehnte Aufruf weder deine Rate-Limits noch deine Tageszaehler beeinflusst.

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Derselbe Code und Status beantworten einen POST /api/proxy/-Aufruf, der exitCountries, exitState, exitCity, exitAsn oder exitOs in einem Tarif ohne Geo-Targeting setzt. Der error-String benennt den Parameter:

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

plan_limit_premium hat die gleiche Form für exitClass: premium in einem Tarif ohne Premium-Exits. Ein Tarif mit Premium-Exits, dessen Premium-Traffic für diesen Zeitraum aufgebraucht ist, wird nicht abgelehnt, es sei denn, ein Proxy-Request gibt einen Exit-Standort an: Der Request wird aus dem Standard-Pool bedient und die Response meldet exitClass: standard. Keiner der beiden Fälle verbraucht einen Premium-Exit. Siehe exitClass.

Kein 403 setzt Retry-After. Warten ändert das Ergebnis nicht.

Gleichzeitige Requests

Concurrency wird pro Endpoint gezählt: Dein Tarif enthält jeweils ein Limit für Single, Proxy und Browser. Der Request, der das Limit überschreitet, wird als 429 mit Retry-After: 1 zurückgegeben:

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

in_flight zählt auch den abgelehnten Request, daher liest er mindestens einen mehr als limit.

Die Lösung besteht darin, deinen eigenen Parallelismus zu begrenzen, statt aggressiver zu wiederholen. Auf einen 429-Fehler zu reagieren, indem derselbe Batch sofort erneut gesendet wird, erzeugt für jeden darin enthaltenen Aufruf einen weiteren 429-Fehler. Siehe Requests parallel ausführen für ein funktionierendes Pattern.

Requests pro Minute

Single und Proxy haben ein Minuten-Kontingent, gemessen über eine gleitende Minute. Nur akzeptierte Requests zählen dazu: Ein abgelehnter Request wird wieder abgezogen. Ein Account, der kontinuierlich etwas mehr als sein Kontingent anfordert, erhält somit sein Kontingent, anstatt fast vollständig abgelehnt zu werden.

{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}

retry_after_seconds gibt an, wie lange es dauert, bis ein weiterer Request zugelassen wird, wenn du dazwischen nichts sendest: mindestens 1 Sekunde und höchstens 120 Sekunden. Der Header Retry-After enthält denselben Wert.

Für wiederholte abgewiesene Requests, die schneller erfolgen, gilt eine eigene Regel. Wenn die durch dieses Kontingent in der gleitenden Minute abgewiesenen Requests mehr als das Doppelte des Kontingents betragen, wird der Aufruf stattdessen mit einer 30-sekündigen Pause abgewiesen:

{
  "error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 540,
  "refused_last_minute": 1250,
  "cooldown": true,
  "retry_after_seconds": 30
}

Ablehnungen während der Pause werden nicht gezählt. Die Pause endet daher von selbst mit Ablauf der Minute, selbst wenn ein Client weiterhin Retries sendet. Um die Pause vom regulären Kontingent zu unterscheiden, lies cooldown statt des Texts von error.

Browser-Requests pro Tag

Browser hat kein Minutenkontingent. Das Tariflimit ist eine Anzahl von Browser-Requests pro Tag, gezählt ab Mitternacht UTC. Der Zähler erfasst jeden zugelassenen Browser-Request, nicht nur erfolgreiche. Ein Browser-Aufruf, der auf Seiten von FourA mit null Credits fehlschlägt, wie der 503 Backend service unavailable, gibt seinen Tages-Slot zurück. Antworten von Browser und Auto, die deine Limits nicht abgelehnt haben, enthalten den Zählerstand und das Limit in den Headern X-FourA-Browser-Used-Today und X-FourA-Browser-Limit-Per-Day: siehe Response Headers.

{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}

Diese Ablehnung enthält weder retry_after_seconds noch Retry-After Header, da die Wartezeit Stunden statt Sekunden beträgt. Behandle dies als Abbruch und plane den nächsten Lauf für Mitternacht UTC.

Guthaben für den Abrechnungszeitraum

Nur abgerechnetes Guthaben zählt, also nur erfolgreiche Requests. Sobald die abgerechnete Summe das dir in diesem Zeitraum verfügbare Guthaben erreicht, werden weitere Requests abgelehnt, bis der Zeitraum zurückgesetzt wird oder du weiteres kaufst.

{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

hard_stop ist die Anzahl abgerechneter Credits, ab der Requests für diesen Zeitraum gestoppt werden. Lies diesen Wert aus dem Body aus, statt ihn zu berechnen: Er enthält bereits alle Credits, die du zusätzlich zum Plan gekauft hast.

Bandbreite für den Abrechnungszeitraum

Pläne mit Bandbreitenlimit lehnen Requests ab, sobald der Standard-Traffic dieses Zeitraums das Limit erreicht. Premium-Traffic hat ein eigenes Kontingent und zählt nicht zu diesem Limit. Gekaufte Bandbreite zählt genauso wie enthaltene Bandbreite, und der error-String gibt an, was dir zur Verfügung steht, nicht nur was der Plan allein enthält.

{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

Bei beiden Periodenlimits ist retry_after_seconds auf 24 Stunden begrenzt; resets_at ist der genaue Zeitpunkt, an dem die Periode wechselt.

Tarifspezifische Limit-Felder

Feld Typ Vorhanden bei Beschreibung
error string alle Für Menschen lesbare Nachricht inklusive des für dich geltenden Limits
reason string alle plan_limit_ plus Name des Limits. Identischer Wert wie im X-FourA-Limit Header.
documentation string alle Link zur Tarifseite
retry_after_seconds number Concurrency, Rate, Credits, Bandbreite Wartezeit. Identischer Wert wie im Retry-After Header.
limit number Concurrency Parallele Requests, die der Tarif auf diesem Endpoint erlaubt
in_flight number Concurrency Laufende Requests auf diesem Endpoint für deinen Account, inklusive des abgelehnten
limit_per_minute number Rate Requests pro Minute, die der Tarif auf diesem Endpoint erlaubt
current_rate number Rate Gezählte Requests im gleitenden 60-Sekunden-Fenster, inklusive des abgelehnten
refused_last_minute number Rate-Pause Requests, die das Minutenkontingent im gleitenden Fenster abgelehnt hat. Nur bei der 30-Sekunden-Pause.
cooldown boolean Rate-Pause true bei der 30-Sekunden-Pause wegen zu schneller Retries. Fehlt bei einer gewöhnlichen Minuten-Ablehnung.
limit_per_day number Browser täglich Browser-Requests, die der Tarif pro Tag erlaubt
used_today number Browser täglich Heute gezählte Browser-Requests, inklusive des abgelehnten
used number Credits Bisher abgerechnete Credits in dieser Periode
hard_stop number Credits Abgerechnete Credits, ab denen Requests in dieser Periode stoppen
used_bytes number Bandbreite Standard-Traffic bisher in dieser Periode, in Bytes. Premium-Traffic ist nicht enthalten.
limit_bytes number Bandbreite Verfügbare Bytes in dieser Periode
resets_at string Credits, Bandbreite ISO-8601-Zeitstempel des Periodenendes

Tariflimits nutzen retry_after_seconds. Die unten stehenden Plattformlimits nutzen retryAfter. Ein Retry-Helper muss beide lesen oder den Retry-After Header auswerten, den Tariflimits setzen und ebenso der 503 API key check temporarily unavailable (siehe Fehler).

Plattform-Limits

Die Plattform-Prüfungen tracken zwei Werte pro Service und einen weiteren über alle Services hinweg:

  • Concurrency: wie viele Requests FourA zeitgleich ausführt.
  • RPM: wie viele Requests FourA in den letzten 60 Sekunden entgegengenommen hat.

Beide Zähler werden von allen geteilt, die diesen Service nutzen. current und limits in den folgenden Antworten beschreiben die Plattform, nicht deinen Account. Wenn du deinen eigenen Wert wissen möchtest, lies in_flight aus einer Tariflimit-Antwort aus oder öffne Usage & Limits im Dashboard.

429: RPM überschritten

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Der Dienst hat die zulässigen Requests für die letzte Minute erreicht. Warte retryAfter Sekunden.

503: Nebenläufigkeit überschritten

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Der Dienst verarbeitet gerade so viele Requests gleichzeitig, wie maximal zulässig ist. Dies löst sich in wenigen Sekunden.

Dienst deaktiviert

Wenn ein Dienst wegen Wartungsarbeiten vorübergehend offline genommen wird, gibt die API einen 503 mit einer anderen Fehlermeldung zurück:

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

Das ist kein Rate Limit. Der Dienst ist vorübergehend nicht verfügbar. Prüfe den Wert von retryAfter und wiederhole den Request nach dieser Anzahl von Sekunden. Das löst sich typischerweise innerhalb von Minuten.

Beide 503-Formate enthalten dieselben Keys. Verzweige daher anhand des error-Strings und niemals danach, welche Felder vorhanden sind. Service disabled steht für Wartung, Service at capacity für Nebenläufigkeit.

Beim Wartungsformat sind current.concurrency und current.rpm immer 0: Der Request wurde abgewiesen, bevor Messungen stattfanden.

Plattform-Limit-Felder

Feld Typ Beschreibung
error string Für Menschen lesbare Fehlermeldung
status number HTTP-Statuscode (429 oder 503)
service string Welcher Dienst den Aufruf verweigert hat: single, proxy, browser oder api
retryAfter number Empfohlene Wartezeit in Sekunden vor einem neuen Versuch
current.concurrency number Requests, die der Dienst über alle Kunden hinweg ausführte, als er ablehnte
current.rpm number Requests, die der Dienst über alle Kunden in den letzten 60 Sekunden verarbeitet hat
limits.maxConcurrency number Geteiltes Concurrency-Kontingent des Dienstes
limits.maxRpm number Geteiltes Pro-Minute-Kontingent des Dienstes

Jede Ablehnung mit einem einzigen Helper verarbeiten

Retry-After ist bei Plan-Limits gesetzt, bei denen sich das Warten lohnt, retry_after_seconds befindet sich in deren Response-Bodies und retryAfter in den Plattform-Bodies. Lies alle drei in dieser Reihenfolge aus und brich bei Plan-Limits ab, die sich durch Warten nicht beheben lassen:

import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

def fetch(url, api_key, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json={"method": "GET", "url": url},
        )

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")

Ein Tageskontingent wird erst nach Stunden wieder verfügbar und ein Periodenkontingent erst nach Tagen. Betrachte sie daher als Stopp und nicht als kurze Pause. Lies resets_at aus dem Body aus, wenn du den nächsten Lauf planen willst.

Tipps

  • Begrenze die Anzahl deiner parallelen Requests, anstatt abgelehnte Batches sofort erneut zu senden. Ein Retry-Sturm macht aus einem einzigen 429 viele weitere.
  • Lies zuerst X-FourA-Limit aus. Der Wert zeigt dir direkt, ob das Limit bei dir oder bei der Plattform liegt; Plattform-Ablehnungen setzen diesen Wert nie.
  • Verwende keine fest codierten Grenzwerte. Jede Antwort zu einem Plan-Limit enthält das Limit, das die Ablehnung ausgelöst hat, und Nutzung & Limits zeigt sie alle.
  • retryAfter ist bei Plattform-Limits je nach Typ festgelegt: 2 Sekunden für Nebenläufigkeit, 5 für RPM, 60 für Wartungsarbeiten.
  • Prüfe error, um die beiden 503-Varianten zu unterscheiden. Beide Formate enthalten current und limits. Eine reine Abfrage nach dem Vorhandensein dieser Felder interpretiert Wartungsarbeiten sonst fälschlicherweise als Problem mit der Nebenläufigkeit.
  • Ein 403 mit X-FourA-Limit betrifft deinen Plan, nicht die Zielseite. Die Zielseite hat nie geantwortet.

Der Proxy-Port hat eigene Grenzwerte

Alles oben Genannte gilt für die JSON-API. Traffic, den du über proxy.foura.ai sendest, unterliegt separaten Plan-Grenzwerten mit anderen Einheiten: gleichzeitig geöffnete Tunnel, Tunnel-Öffnungen pro Minute und Standard-Traffic für den Abrechnungszeitraum. Diese Ablehnungen werden als HTTP-Status mit einem X-Foura-Error-Header statt als JSON-Body geliefert, da ein CONNECT keinen Body enthalten kann. Unter Proxy-Port findest du die Statustabelle und unter Messung deines Plans erfährst du, aus welchem Pool die Gigabytes des Ports abgezogen werden.

Aktualisiert: 6. November 2026