Rate Limits

Rate Limits sind Einschränkungen, die festlegen, wie oft ein Nutzer oder Client unsere Services innerhalb eines bestimmten Zeitraums aufrufen darf.

Warum haben wir Rate Limits?

Rate Limits sind wichtig, um Zuverlässigkeit und Fairness sicherzustellen. Wir setzen sie aus mehreren Gründen ein:

Schutz vor Störungen: Rate Limits verhindern, dass unsere API durch zu viele Requests (z. B. durch Missbrauch) überlastet wird, was Performance-Probleme oder Ausfälle verursachen könnte.
Faire Ressourcenzuteilung: Ohne Rate Limits könnte ein einzelner Nutzer unverhältnismässig viele Serverressourcen belegen und damit die Antwortzeiten für andere verschlechtern.
Infrastruktur-Optimierung: Rate Limits helfen, Serverlast kontrolliert zu steuern. Bei wachsender Nutzung verhindern sie, dass Traffic-Spitzen unsere Infrastruktur überfordern.

Wie funktionieren die Rate Limits?

Unser Rate-Limiting verwendet ein Sliding-Window und misst Requests pro Minute (RPM). Die Limits gelten pro Benutzerkonto und umfassen alle Access-Tokens dieses Kontos. Je nach Rechenaufwand und Ressourcenbedarf unterscheiden sich die Limits je Endpunkt.

Sliding Window Implementation

Das Sliding-Window wird kontinuierlich ausgewertet, nicht in festen Intervallen zurückgesetzt. Beispiel bei einem Limit von 60 RPM:

Um 10:00:00 können Sie 60 Requests senden
Um 10:00:30 können Sie weitere Requests senden, solange die Requests der letzten 60 Sekunden zusammen das Limit nicht überschreiten
Das Fenster verschiebt sich laufend und hält das Limit für jeden beliebigen 60-Sekunden-Zeitraum ein

Endpounkt-spezifische Rate Limits

Rate Limits unterscheiden sich je Endpunkt, passend zu deren Ressourcenbedarf:

Endpoint Category	Rate Limit (RPM)	Examples
Food Lookup	60	`/food/:id`
Search	120	`/search`
Nutrition Evaluation	60	`/evaluate/nutrition-summary`, `/evaluate/macro-distribution`, `/evaluate/healthy-eating-index`

Rate Limit Headers

Sie können Ihren Rate-Limit-Status über HTTP-Response-Header in jeder API-Antwort beobachten:

Header Name	Sample Value	Description
`X-RateLimit-Limit`	`60`	Maximale Anzahl Requests pro Minute für diesen Endpunkt
`X-RateLimit-Used`	`15`	Anzahl genutzter Requests im aktuellen Fenster
`X-RateLimit-Remaining`	`45`	Verbleibende Requests im aktuellen Fenster
`X-RateLimit-Reset`	`1703123456`	Unix-Timestamp, wann das Rate-Limit-Fenster wieder Kapazität frei gibt

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Used: 15
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703123456
Content-Type: application/json

Rate Limit Errors

Wenn Sie Ihr Rate Limit überschreiten, liefert die API den Statuscode 429 Too Many Requests mit Details, ab wann Sie erneut versuchen können:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "details": {
      "limit": 60,
      "used": 60,
      "reset_at": "2024-12-01T10:01:00Z"
    }
  }
}

Zusätzlich enthält die Antwort einen X-Retry-After Header mit der Anzahl Sekunden, die Sie vor dem Retry warten sollten.

Error Mitigation Strategies

Retrying with Exponential Backoff

Ein bewährter Ansatz ist, Requests bei Rate-Limit-Fehlern automatisch mit exponentiellem Backoff zu wiederholen:

async function apiRequestWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status !== 429) {
        return response;
      }

      if (attempt === maxRetries) {
        throw new Error("Max retries exceeded");
      }

      // Use X-Retry-After header if available, otherwise exponential backoff
      const retryAfter = response.headers.get("X-Retry-After");
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.pow(2, attempt) * 1000 + Math.random() * 1000;

      await new Promise((resolve) => setTimeout(resolve, delay));
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

Das hat mehrere Vorteile:

Automatische Erholung ohne Crashes oder Datenlücken
Respektiert Server-Hinweise durch Nutzung von X-Retry-After (falls vorhanden)
Steigende Wartezeiten bei wiederholten Fehlern
Random Jitter verhindert, dass alle Clients gleichzeitig erneut senden

Caching and Data Storage

Das Cachen von API-Antworten ist eine effektive Strategie, um Request-Frequenz zu senken und innerhalb der Rate Limits zu bleiben.

Details zur technischen Umsetzung und zu rechtlichen Anforderungen finden Sie unter API-Antworten cachen.

Best Practices

Proactive Rate Limit Management

Beobachten Sie Ihr Nutzungsverhalten über die Header X-RateLimit-Used und X-RateLimit-Remaining in jeder Antwort. Sinnvoll sind z. B. automatische Warnungen ab 80% Auslastung, um unerwartete Unterbrechungen zu vermeiden.

Robust Error Handling

Implementieren Sie bei Rate-Limit-Fehlern Retry-Logik mit exponentiellem Backoff und berücksichtigen Sie X-Retry-After. Geben Sie während Wartezeiten sinnvolles Feedback und halten Sie aussagekräftige Logs vor, um Muster zu erkennen.

Request Optimization

Nutzen Sie Response-Caching, um API-Calls zu reduzieren. Überprüfen Sie Request-Patterns regelmässig, um Effizienzpotenziale zu finden und mit Abstand innerhalb der Limits zu bleiben.

Need Higher Rate Limits?

Unsere Rate Limits sind so ausgelegt, dass typische Nutzungsszenarien abgedeckt sind und die Stabilität geschützt bleibt. Wenn die aktuellen Limits Ihren legitimen Use Case behindern, kontaktieren Sie bitte unser Support-Team unter support@newtrition.com. Wir finden gemeinsam eine passende Lösung.

Bitte schicken Sie bei der Anfrage möglichst mit:

Ihren Use Case und erwartete Request-Patterns
Welche Rate Limits konkret Probleme verursachen
Ungefähren Request-Volumenbedarf
Relevanten Kontext (falls vorhanden)