Rate-Limits

Die Kanman API hat Rate-Limits, um faire Nutzung und Systemstabilität sicherzustellen. Diese Limits schützen die API vor Überlastung und stellen sicher, dass alle Benutzer eine konsistente Leistung erhalten. Dieses Dokument erklärt, wie Limits funktionieren, wie Sie Ihre Nutzung überwachen und was zu tun ist, wenn Sie diese erreichen.

Die Limits sind großzügig für normale Nutzung bemessen, aber wenn Sie große Datensynchronisierungen durchführen oder intensiv automatisieren, sollten Sie verstehen, wie Sie innerhalb Ihres Kontingents bleiben.

Monatliche Kontingente

Kontingente werden am ersten Tag jedes Kalendermonats zurückgesetzt.

Ihre Nutzung überprüfen

Über Header

Jede API-Antwort enthält Nutzungs-Header:

X-RateLimit-Limit: 12000
X-RateLimit-Remaining: 11847
X-RateLimit-Reset: 2024-02-01T00:00:00Z

Diese Header ermöglichen es Ihnen, Ihre Nutzung programmgesteuert zu überwachen und Ihr Verhalten anzupassen, bevor Sie das Limit erreichen.

Über Einstellungen

Überprüfen Sie die Nutzung in der Kanman-App:

1. Gehen Sie zu Einstellungen > API-Token
2. Sehen Sie den Abschnitt API-Nutzung
3. Betrachten Sie die Nutzung des aktuellen Monats und das verbleibende Kontingent

Kontingent überschritten

Wenn Sie Ihr Kontingent überschreiten:

Antwort

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monatliches API-Kontingent überschritten",
    "limit": 12000,
    "reset": "2024-02-01T00:00:00Z"
  }
}

HTTP-Status

HTTP/1.1 429 Too Many Requests

Was zu tun ist

1. Auf monatliches Zurücksetzen warten
2. Ein Kontingent-Zusatzpaket kaufen
3. Auf den Teams-Tarif upgraden

Zusatzpakete

Kaufen Sie zusätzliche API-Aufrufe:

Zusatzpakete sind wiederkehrende Abonnements, die zu Ihrem Basiskontingent hinzugefügt werden.

Kauf

1. Gehen Sie zu Einstellungen > Abonnement
2. Klicken Sie auf API-Aufrufe hinzufügen
3. Schließen Sie den Checkout ab
4. Zusätzliches Kontingent gilt sofort

Optimierungstipps

API-Aufrufe reduzieren

1. Batch-Lesen: Boards mit Projekten in einem Aufruf abrufen
2. Antworten cachen: Daten lokal speichern, wenn angemessen
3. Webhooks verwenden: Push-Benachrichtigungen statt Polling erhalten

Effizientes Polling

Wenn Sie pollen müssen:

// Schlecht: Jede Sekunde pollen
setInterval(() => fetchTasks(), 1000);

// Gut: Alle 5 Minuten pollen
setInterval(() => fetchTasks(), 5 * 60 * 1000);

// Besser: Webhooks stattdessen verwenden

Beispiel: Effizienter Sync

// Statt einzelner Aufgabenabrufe
for (const taskId of taskIds) {
  await fetch(`/tasks/${taskId}`); // 100 Aufrufe!
}

// Alle Aufgaben eines Projekts auf einmal abrufen
await fetch(`/projects/${projectId}/tasks`); // 1 Aufruf!

Rate-Limit Best Practices

429-Fehler behandeln

async function apiCall(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    // Reset-Zeit aus Header holen
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitTime = new Date(resetTime) - new Date();

    // Wenn Reset bald, warten. Sonst fehlschlagen.
    if (waitTime < 60000) { // Weniger als 1 Minute
      await sleep(waitTime);
      return apiCall(url, options, retries - 1);
    }
  }

  return response;
}

Nutzung überwachen

function checkRateLimits(response) {
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
  const usagePercent = ((limit - remaining) / limit) * 100;

  if (usagePercent > 80) {
    console.warn(`API-Nutzung bei ${usagePercent.toFixed(1)}%`);
    // Ihr Team alarmieren oder Verhalten anpassen
  }
}

Pro-Sekunde-Limits

Zusätzlich zu monatlichen Kontingenten gibt es Pro-Sekunde-Limits:

Das Überschreiten von Pro-Sekunde-Limits gibt 429 Too Many Requests mit einem Retry-After-Header zurück.

Ausgenommene Operationen

Einige Operationen zählen nicht zum Kontingent:

• Token-Validierung (Authentifizierungsprüfung)
• Health-Check-Endpunkt
• OPTIONS-Anfragen (CORS-Preflight)

Verwandte Themen

• Authentifizierung - API-Token
• Fehler - Fehlerbehandlung
• Webhooks - Ereignis-Benachrichtigungen