Rate Limiting

:::caution Geplant – noch nicht verfügbar Diese Seite beschreibt ein API-weites Rate-Limiting-Verfahren, das noch nicht implementiert ist. Die öffentliche REST-API liefert derzeit keine X-RateLimit-*-Header oder 429-Antworten für allgemeine Endpoints; 429 wird heute nur von Streaming-Endpoints (SSE) und Billing-Ausgabenlimits verwendet. Die unten genannten Limits, Header und Beispiele veranschaulichen eine geplante Funktion. :::

Die Tourfold-API setzt Rate Limiting ein, um eine faire Nutzung sicherzustellen und die Servicequalität für alle Nutzer zu erhalten. Rate Limits korrekt zu verstehen und zu behandeln ist entscheidend, um zuverlässige Anwendungen zu bauen.

Funktionsweise des Rate Limitings

Rate Limits gelten pro API-Schlüssel oder Benutzer-Token und werden über ein Sliding-Window verfolgt. Verschiedene Endpoints können unterschiedliche Limits haben, abhängig davon, wie ressourcenintensiv sie sind.

Rate-Limit-Header

Jede API-Antwort enthält Informationen zum Rate Limit in den Headern:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642233600
X-RateLimit-Window: 3600

Header	Beschreibung
`X-RateLimit-Limit`	Maximale Anzahl Anfragen im aktuellen Fenster
`X-RateLimit-Remaining`	Anzahl verbleibender Anfragen im aktuellen Fenster
`X-RateLimit-Reset`	Unix-Timestamp, wann das aktuelle Fenster zurückgesetzt wird
`X-RateLimit-Window`	Fenstergröße in Sekunden

Rate-Limit-Stufen

Stufe	Anfragen pro Stunde	Burst-Limit	Beschreibung
Standard	1.000	1.000	Produktivanwendungen
Enterprise	Individuell	Individuell	Individuelle Limits für Enterprise-Kunden

Standard-Limits

Allgemeine Endpoints

Lesezugriffe: 1.000 Anfragen pro Stunde
Schreibzugriffe: 500 Anfragen pro Stunde
Suchanfragen: 200 Anfragen pro Stunde

Limits einzelner Endpoints

Endpoint	Limit	Fenster	Hinweise
`GET /api/v2/tours`	1.000	1 Stunde	Touren auflisten
`POST /api/v2/tours`	500	1 Stunde	Tour anlegen
`GET /api/v2/drivers`	1.000	1 Stunde	Fahrer auflisten

Mit Rate Limits umgehen

Rate-Limit-Antwort

Beim Überschreiten des Rate Limits erhalten Sie eine Antwort mit Status 429 Too Many Requests:

{
  "type": "https://tourfold.com/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "detail": "You have exceeded the rate limit for this endpoint",
  "data": {
    "limit": 1000,
    "remaining": 0,
    "reset_time": 1642233600,
    "retry_after": 3600,
    "window_size": 3600
  }
}

Retry-After-Header

Die Antwort enthält außerdem einen Retry-After-Header, der angibt, wann Sie erneut anfragen können:

Retry-After: 3600

Best Practices

Exponential Backoff implementieren

#!/bin/bash

make_api_request() {
    local url="$1"
    local retries="${2:-3}"
    
    response=$(curl -s -w "%{http_code}" -o /tmp/response.json "$url")
    http_code="${response: -3}"
    
    if [ "$http_code" -eq 429 ]; then
        retry_after=$(curl -s -I "$url" | grep -i "retry-after" | cut -d' ' -f2 | tr -d '\r')
        
        if [ "$retries" -gt 0 ]; then
            echo "Rate limited. Waiting $retry_after seconds before retry..."
            sleep "$retry_after"
            make_api_request "$url" $((retries - 1))
        else
            echo "Max retries exceeded"
            exit 1
        fi
    else
        cat /tmp/response.json
    fi
}

# Anwendungsbeispiel
make_api_request "https://api.tourfold.com/api/v2/tours" 3

Rate Limits überwachen

#!/bin/bash

check_rate_limit() {
    local url="$1"
    
    # Anfrage stellen und Header erfassen
    response=$(curl -s -I -H "Authorization: Bearer YOUR_TOKEN" "$url")
    
    # Rate-Limit-Header extrahieren
    limit=$(echo "$response" | grep -i "x-ratelimit-limit" | cut -d' ' -f2 | tr -d '\r')
    remaining=$(echo "$response" | grep -i "x-ratelimit-remaining" | cut -d' ' -f2 | tr -d '\r')
    reset=$(echo "$response" | grep -i "x-ratelimit-reset" | cut -d' ' -f2 | tr -d '\r')
    
    if [ -n "$limit" ] && [ -n "$remaining" ]; then
        usage_percentage=$(( (limit - remaining) * 100 / limit ))
        
        echo "Rate Limit Usage: ${usage_percentage}%"
        echo "Remaining: $remaining / $limit"
        echo "Reset: $(date -d @$reset)"
        
        if [ "$usage_percentage" -gt 80 ]; then
            echo "WARNING: High rate limit usage!"
        fi
    fi
}

# Anwendungsbeispiel
check_rate_limit "https://api.tourfold.com/api/v2/tours"

Antworten cachen

#!/bin/bash

# Einfaches dateibasiertes Caching
cache_dir="/tmp/tourfold_cache"
mkdir -p "$cache_dir"

get_cached_response() {
    local url="$1"
    local cache_file="$cache_dir/$(echo "$url" | md5sum | cut -d' ' -f1)"
    
    # Prüfen, ob der Cache existiert und jünger als 5 Minuten ist
    if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -c %Y "$cache_file"))) -lt 300 ]; then
        echo "Using cached response for: $url"
        cat "$cache_file"
    else
        echo "Fetching fresh data for: $url"
        response=$(curl -s -H "Authorization: Bearer YOUR_TOKEN" "$url")
        echo "$response" > "$cache_file"
        echo "$response"
    fi
}

# Anwendungsbeispiel
get_cached_response "https://api.tourfold.com/api/v2/tours"

Strategien für Rate Limits

1. Anfragen bündeln

Bündeln Sie Anfragen, wo möglich, statt viele einzelne Aufrufe zu machen:

# Statt vieler einzelner Anfragen
for tour_id in tour_123 tour_456 tour_789; do
    curl -H "Authorization: Bearer YOUR_TOKEN" \
         "https://api.tourfold.com/api/v2/tours/$tour_id"
done

# Batch-Endpoint nutzen
curl -X POST "https://api.tourfold.com/api/v2/tours/batch" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{
       "tour_ids": ["tour_123", "tour_456", "tour_789"]
     }'

2. Paginierung optimieren

Nutzen Sie passende Seitengrößen, um die Anzahl der Anfragen zu reduzieren:

# Größere Seitengrößen verwenden, wenn möglich
curl "https://api.tourfold.com/api/v2/tours?page=0&size=100" \
     -H "Authorization: Bearer YOUR_TOKEN"

3. Webhook-Integration

Verwenden Sie Webhooks statt Polling für Echtzeit-Updates:

# Statt zu pollen
while true; do
    curl "https://api.tourfold.com/api/v2/tours?updated_since=$last_check" \
         -H "Authorization: Bearer YOUR_TOKEN"
    sleep 60
done

# Webhook-Endpoint registrieren
curl -X POST "https://api.tourfold.com/api/v2/webhook-endpoints" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{
       "display_name": "Tour lifecycle listener",
       "endpoint_url": "https://your-server.com/webhook",
       "signature_scheme": "HMAC_SHA256",
       "enabled": true,
       "retry": true,
       "subscriptions": ["device.updated", "user.updated"]
     }'

Monitoring und Alerts

Alerts einrichten

#!/bin/bash

# Einfaches Skript zum Rate-Limit-Monitoring
monitor_rate_limits() {
    local url="$1"
    local log_file="/tmp/rate_limit_monitor.log"
    
    # Aktuelle Nutzung abrufen
    response=$(curl -s -I -H "Authorization: Bearer YOUR_TOKEN" "$url")
    limit=$(echo "$response" | grep -i "x-ratelimit-limit" | cut -d' ' -f2 | tr -d '\r')
    remaining=$(echo "$response" | grep -i "x-ratelimit-remaining" | cut -d' ' -f2 | tr -d '\r')
    
    if [ -n "$limit" ] && [ -n "$remaining" ]; then
        usage_percentage=$(( (limit - remaining) * 100 / limit ))
        
        # Nutzung protokollieren
        echo "$(date): Usage: ${usage_percentage}% (${remaining}/${limit})" >> "$log_file"
        
        # Alarm bei kritischer Nutzung
        if [ "$usage_percentage" -gt 90 ]; then
            echo "CRITICAL: Rate limit usage at ${usage_percentage}%!" | tee -a "$log_file"
            # Alarm versenden (E-Mail, Slack usw.)
        fi
    fi
}

# Alle 5 Minuten überwachen
while true; do
    monitor_rate_limits "https://api.tourfold.com/api/v2/tours"
    sleep 300
done

Höhere Rate Limits anfragen

Höhere Limits beantragen

Kontaktieren Sie unser Support-Team, um höhere Rate Limits zu beantragen:

Nutzungs-Kennzahlen mitliefern: Zeigen Sie Ihre aktuellen Nutzungsmuster
Anwendungsfall erläutern: Beschreiben Sie die Anforderungen Ihrer Anwendung
Notwendigkeit belegen: Zeigen Sie, warum höhere Limits erforderlich sind

Enterprise-Tarife

Enterprise-Kunden erhalten:

Individuelle Rate Limits
Dedizierte Infrastruktur
Priorisierten Support
SLA-Garantien

Häufige Fehler vermeiden

❌ Rate Limits nicht ignorieren

# Schlecht: Keine Behandlung von Rate Limits
curl "https://api.tourfold.com/api/v2/tours"

❌ Nicht sofort erneut versuchen

# Schlecht: Sofortiger Retry
if [ $http_code -eq 429 ]; then
    curl "https://api.tourfold.com/api/v2/tours"  # Wird wieder fehlschlagen
fi

✅ Rate Limits korrekt behandeln

# Gut: Korrekte Behandlung von Rate Limits
make_request() {
    response=$(curl -s -w "%{http_code}" -o /tmp/response.json \
              -H "Authorization: Bearer YOUR_TOKEN" \
              "https://api.tourfold.com/api/v2/tours")
    http_code="${response: -3}"
    
    if [ "$http_code" -eq 429 ]; then
        retry_after=$(curl -s -I "https://api.tourfold.com/api/v2/tours" | \
                     grep -i "retry-after" | cut -d' ' -f2 | tr -d '\r')
        echo "Rate limited. Waiting $retry_after seconds..."
        sleep "$retry_after"
        make_request
    else
        cat /tmp/response.json
    fi
}

Rate Limits testen

Kontrollierte Testumgebung

Testen Sie die Wiederholungslogik lokal oder in einer privaten Nicht-Produktionsumgebung, die für Ihre Integration bereitgestellt wurde. Halten Sie die API-Basis-URL konfigurierbar und führen Sie keine Lasttests gegen die Produktions-API aus.

Lasttests

#!/bin/bash

# Einfacher Lasttest
load_test() {
    local endpoint="$1"
    local count="${2:-100}"
    local rate_limited=0
    
    echo "Testing $count requests to $endpoint..."
    
    for ((i=1; i<=count; i++)); do
        response=$(curl -s -w "%{http_code}" -o /dev/null \
                  -H "Authorization: Bearer YOUR_TOKEN" \
                  "$endpoint")
        http_code="${response: -3}"
        
        if [ "$http_code" -eq 429 ]; then
            ((rate_limited++))
        fi
        
        # Kleine Verzögerung, um nicht zu überlasten
        sleep 0.1
    done
    
    echo "Rate limited requests: $rate_limited out of $count"
}

# Anwendungsbeispiel
load_test "https://api.tourfold.com/api/v2/tours" 50

Nächste Schritte

Lernen Sie die Fehlerbehandlung kennen
Verstehen Sie Paginierung und Filterung
Entdecken Sie Server-Sent Events für Echtzeit-Updates

Funktionsweise des Rate Limitings​

Rate-Limit-Header​

Rate-Limit-Stufen​

Standard-Limits​

Allgemeine Endpoints​

Limits einzelner Endpoints​

Mit Rate Limits umgehen​

Rate-Limit-Antwort​

Retry-After-Header​

Best Practices​

Exponential Backoff implementieren​

Rate Limits überwachen​

Antworten cachen​

Strategien für Rate Limits​

1. Anfragen bündeln​

2. Paginierung optimieren​

3. Webhook-Integration​

Monitoring und Alerts​

Alerts einrichten​

Höhere Rate Limits anfragen​

Höhere Limits beantragen​

Enterprise-Tarife​

Häufige Fehler vermeiden​

❌ Rate Limits nicht ignorieren​

❌ Nicht sofort erneut versuchen​

✅ Rate Limits korrekt behandeln​

Rate Limits testen​

Kontrollierte Testumgebung​

Lasttests​

Nächste Schritte​