Rate Limits

Jeder FourA-API-Request durchläuft ein Rate Limiting. Du wirst auf zwei Arten von Limits stoßen: Concurrency (gleichzeitige Requests) und RPM (Requests pro Minute). Beide werden pro Service erzwungen.

Wie Rate Limits funktionieren

Die API erzwingt Limits auf zwei Ebenen:

Globales API-Limit: Gilt für alle Requests unabhängig vom Endpoint. Diese Prüfung läuft zuerst.
Service-spezifisches Limit: Gilt separat für jeden Endpoint (single, proxy, browser). Diese Prüfung läuft nur, wenn das globale Limit erfolgreich bestanden wurde.

Wenn das globale Limit erreicht wird, läuft die service-spezifische Prüfung nicht. Ein Request muss beide Prüfungen bestehen, bevor er das Backend erreicht.

Jede Ebene erfasst zwei Metriken:

Concurrency: Wie viele Requests gleichzeitig laufen.
RPM: Wie viele Requests du in den letzten 60 Sekunden gesendet hast.

Rate-Limit-Antworten

Wenn du ein Limit erreichst, gibt die API eine JSON-Response mit deiner aktuellen Nutzung und den geltenden Limits zurück.

429: RPM überschritten

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

Du hast in der letzten Minute zu viele Requests gesendet. Warte den retryAfter-Zeitraum ab, bevor du weitere sendest.

503: Concurrency überschritten

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

Es laufen zu viele Requests gleichzeitig. Einige deiner früheren Requests sind noch nicht abgeschlossen.

Service deaktiviert

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

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

Dies ist kein Rate Limit. Der Service ist vorübergehend nicht verfügbar. Prüfe den retryAfter-Wert und versuche es nach dieser Anzahl von Sekunden erneut. Dies ist normalerweise innerhalb von Minuten behoben.

Verwechsle dies nicht mit der Concurrency-503. Eine "Service disabled"-Response enthält keine current- oder limits-Felder.

Response-Felder

Feld	Typ	Beschreibung
`error`	string	Lesbare Fehlermeldung
`status`	number	HTTP-Statuscode (429 oder 503)
`service`	string	Welcher Service das Limit erreicht hat: single, proxy, browser oder api
`retryAfter`	number	Empfohlene Wartezeit in Sekunden vor dem nächsten Versuch
`current.concurrency`	number	Deine aktuelle Anzahl aktiver Requests
`current.rpm`	number	Deine Requests in den letzten 60 Sekunden
`limits.maxConcurrency`	number	Maximal erlaubte gleichzeitige Requests
`limits.maxRpm`	number	Maximal erlaubte Requests pro Minute

Umgang mit Rate Limits

Nutze das retryAfter-Feld, um ein Backoff zu implementieren:

import requests
import time

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

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

Tipps

Prüfe die current-Felder in den Rate-Limit-Responses, um deine Nutzungsmuster zu verstehen.
Wenn du ständig an Concurrency-Limits stößt, reduziere die Anzahl paralleler Requests.
Wenn du an RPM-Limits stößt, füge eine kurze Verzögerung zwischen den Requests hinzu oder verteile sie über ein längeres Zeitfenster.
Der retryAfter-Wert variiert je nach Limit-Typ: 2 Sekunden bei Concurrency, 5 Sekunden bei RPM.
Eine "Service disabled"-Response bedeutet, dass Wartungsarbeiten durchgeführt werden. Sende nicht ununterbrochen Requests an den Endpoint.