Rate Limiting

Übersicht

Um eine faire Nutzung zu gewährleisten und eine optimale Performance für alle Benutzer aufrechtzuerhalten, implementiert die Curosa-API eine Ratenbegrenzung (Rate Limiting) für alle Endpunkte. Rate-Limits helfen dabei, die API vor Überlastung zu schützen und einen zuverlässigen Dienst für alle sicherzustellen.

Rate-Limits

Rate-Limits werden pro Endpunkt angewendet:

• Login-Endpunkt (POST /login): 10 Anfragen pro Stunde
• Alle anderen dokumentierten API-Endpunkte: 3.600 Anfragen pro Stunde

Beachten Sie bei Ausnahmen immer die endpunktspezifische Dokumentation.

Rate-Limit-Header

Jede API-Antwort enthält Rate-Limit-Header, damit Sie die Nutzung in Echtzeit überwachen können:

• x-ratelimit-limit: Das Anfragelimit für das aktuelle Zeitfenster
• x-ratelimit-remaining: Verbleibende Anfragen im aktuellen Zeitfenster

Rate-Limit-Antworten

Wenn Sie das Rate-Limit überschreiten, gibt die API 429 Too Many Requests zurück:

{"success":false,"message":"Too many requests. Please try again later."}

Wenn Sie diese Antwort erhalten, sollten Sie Ihre Anfragen pausieren und es nach einer kurzen Verzögerung erneut versuchen.

Best Practices

Um das Erreichen von Rate-Limits zu vermeiden und eine optimale API-Nutzung zu gewährleisten, befolgen Sie diese Empfehlungen:

1. Exponentielles Backoff implementieren

Wenn Sie eine 429-Antwort erhalten, implementieren Sie ein exponentielles Backoff in Ihrer Retry-Logik:

• Warten Sie 1 Sekunde vor dem ersten Wiederholungsversuch
• Verdoppeln Sie die Wartezeit für jeden weiteren Versuch (2s, 4s, 8s usw.)
• Legen Sie ein maximales Limit für Wiederholungsversuche fest, um Endlosschleifen zu vermeiden

Beispiel für eine Retry-Logik:

Ursprüngliche Anfrage schlägt fehl → 1s warten → Wiederholen
Schlägt weiterhin fehl → 2s warten → Wiederholen
Schlägt weiterhin fehl → 4s warten → Wiederholen

2. Antworten nach Bedarf zwischenspeichern

Reduzieren Sie unnötige API-Aufrufe, indem Sie Antworten zwischenspeichern, die sich nicht häufig ändern:

• Referenzdaten zwischenspeichern (Produktkataloge, Kategorien usw.)
• Legen Sie angemessene Ablaufzeiten für den Cache fest, basierend auf der Volatilität der Daten
• Verwenden Sie bedingte Anfragen (conditional requests), sofern verfügbar

3. Webhooks anstelle von Polling verwenden

Anstatt Endpunkte wiederholt auf Updates abzufragen (Polling), verwenden Sie Webhooks, um Benachrichtigungen in Echtzeit zu erhalten:

• Webhooks senden Ihnen Updates automatisch zu
• Dadurch entfallen häufige Polling-Anfragen
• Effizienter und reduziert die Last auf beiden Systemen
• Informationen zur Einrichtung finden Sie in der Webhooks-Dokumentation

4. Batch-Anfragen nach Möglichkeit verwenden

Wenn Sie mehrere Ressourcen abrufen müssen, prüfen Sie, ob die API Batch-Operationen unterstützt, um die Anzahl der Einzelanfragen zu reduzieren.

5. Überwachen Sie Ihre Nutzung

Behalten Sie Ihre API-Nutzungsmuster im Auge und passen Sie Ihre Integration so an, dass sie deutlich innerhalb der Rate-Limits bleibt, um Spielraum für Aktivitätsspitzen zu lassen.

Benötigen Sie höhere Limits?

Wenn Ihre Anwendung höhere Rate-Limits erfordert, wenden Sie sich bitte an unser Support-Team, um Ihren Anwendungsfall zu besprechen und verfügbare Optionen zu prüfen.