Rate Limits & Kontingente

Die API verwendet Rate Limits, um faire Nutzung zu gewährleisten und die Servicequalität für alle Partner sicherzustellen.

Rate Limits

Anfragen pro Minute

Limit-Typ	Grenze	Beschreibung
Pro Token	100/min	Jeder API-Token hat ein eigenes Limit
Pro Partner	1.000/min	Gesamtlimit über alle Tokens eines Partners
Matching-Endpoint	10/sec	Spezielles Limit für rechenintensive Matching-Anfragen

Rate Limit Header

Jede Response enthält Header mit Limit-Informationen:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706540400

Header	Beschreibung
`X-RateLimit-Limit`	Maximale Anfragen pro Fenster
`X-RateLimit-Remaining`	Verbleibende Anfragen
`X-RateLimit-Reset`	Unix-Timestamp, wann das Limit zurückgesetzt wird

Bei Limit-Überschreitung

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before retrying.",
    "retry_after": 30
  }
}

Warte die im Retry-After Header angegebene Zeit (in Sekunden), bevor du weitere Anfragen sendest.

Fair-Use-Kontingente

Zusätzlich zu den Rate Limits gibt es quartalsweise Fair-Use-Kontingente.

Kontingent-Grenzen nach Tier

Tier	Aktive Organisationen	Matching-Anfragen/Jahr
S - Small	≤ 100	10.000
M - Medium	≤ 500	50.000
L - Large	≤ 1.000	100.000

Was ist eine "Aktive Organisation"?

Eine Organisation gilt als "aktiv" in einem Quartal, wenn mindestens eine Matching-Anfrage mit ihrer organization_id durchgeführt wurde.

Beispiel: - Organisation "org-123" führt 50 Matching-Anfragen aus → zählt als 1 aktive Organisation - Organisation "org-456" führt 200 Matching-Anfragen aus → zählt als 1 aktive Organisation - Gesamt: 2 aktive Organisationen

Kontingent-Warnung

Bei 90% Auslastung des Kontingents: - Du erhältst eine E-Mail an die hinterlegte Kontakt-Adresse - Im Partner-Dashboard erscheint ein Warnhinweis - Die quota-Response zeigt warning: true

Was passiert bei Überschreitung?

Die API bleibt funktionsfähig – wir blockieren keine Anfragen bei Kontingent-Überschreitung. Allerdings: - Die Überschreitung wird dokumentiert - Es erfolgt eine Nachberechnung gemäß Vertrag - Wir kontaktieren dich für ein mögliches Tier-Upgrade

Best Practices

Exponential Backoff

Bei 429-Fehlern implementiere Exponential Backoff:

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

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Request-Batching

Statt vieler einzelner Grant-Anfragen, nutze die Pagination:

# ❌ Schlecht: Viele einzelne Anfragen
GET /api/v1/grants/id1
GET /api/v1/grants/id2
GET /api/v1/grants/id3

# ✅ Gut: Eine Anfrage mit mehr Ergebnissen
GET /api/v1/grants?per_page=100

Caching

Implementiere clientseitiges Caching für: - Grant-Details (ändern sich selten) – Cache: 24 Stunden - Matching-Ergebnisse – Cache: 24 Stunden - Usage-Statistiken – Cache: 5 Minuten

Kontingent überwachen

Prüfe regelmäßig dein Kontingent:

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/usage/quota" \
  -H "Authorization: Bearer rfk_dein_token"

Integriere eine Warnung in dein Monitoring, wenn percentage > 80%.

Höhere Limits benötigt?

Kontaktiere unser Partner-Team, wenn: - Deine Rate Limits regelmäßig erreicht werden - Du ein höheres Fair-Use-Kontingent benötigst - Du auf einen höheren Tier upgraden möchtest

Wir finden gemeinsam die passende Lösung für deine Anforderungen.

Suche

Menu