Entwickler Limits und Fehler

Limits und Fehlercodes

Grenzen der CLUP.life-API (Anfragen pro Minute, Schlüssel, Webhooks) und alle Fehlercodes mit Bedeutung und Abhilfe.

Limits#

Grenze	Basis (Personenschlüssel)	Premium (Organisationsschlüssel)
Anfragen pro Minute und Schlüssel	60	600
Aktive Schlüssel	3	20
Webhooks je Organisation	—	10
Längste Gültigkeit eines Schlüssels	365 Tage	365 Tage

Die Begrenzung gilt je Schlüssel in einem gleitenden Fenster von einer Minute, zusätzlich gilt die allgemeine Begrenzung je IP-Adresse und Route. Bei Überschreitung antwortet die API mit 429 RATE_LIMITED und dem Kopf Retry-After (Sekunden). Zeiträume bei Terminen sind auf 400 Tage begrenzt, Listen auf 100 Einträge je Seite.

Tipps: Nutze Cursor-Seiten mit limit=100 statt vieler kleiner Aufrufe, speichere Ergebnisse zwischen (Websites 5–15 Minuten) und nimm für Änderungen Webhooks statt ständigem Abfragen.

Fehlerformat#

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "Dem Schlüssel fehlt der Bereich events:write."
}

Verlasse dich auf code (stabil), nicht auf den Wortlaut der message (deutsch, kann sich ändern). Bei Validierungsfehlern nennt errors die betroffenen Felder.

Fehlercodes#

Status	Code	Bedeutung und Abhilfe
400	`VALIDATION_FAILED`	Eingabe ungültig; `errors` nennt die Felder.
401	`INVALID_API_KEY`	Schlüssel falsch, abgelaufen, widerrufen oder das Konto ist gesperrt.
403	`INSUFFICIENT_SCOPE`	Dem Schlüssel fehlt der Bereich für diese Route. Neuen Schlüssel mit mehr Bereichen anlegen.
403	`API_KEY_NOT_ALLOWED`	Diese Route ist mit keinem Schlüssel erreichbar (Konto, Finanzen, Kinder, Verwaltung).
403	`PREMIUM_REQUIRED`	Organisationsschlüssel, Schreiben und Webhooks brauchen Premium der Organisation.
403	`FORBIDDEN`	Die Person hinter dem Schlüssel hat dafür nicht das Recht.
403	`ADULT_ONLY`	Schlüssel können nur Erwachsenenkonten anlegen.
403	`WRITE_NEEDS_ORGANIZATION`	Schreibende Bereiche gibt es nur für Schlüssel einer Organisation.
403	`ORGANIZATION_KEY_REQUIRED`	Schreibende Aufrufe brauchen einen an eine Organisation gebundenen Schlüssel.
403	`RANGE_INVALID`	Zeitraum muss vorwärts laufen und darf höchstens 400 Tage umfassen.
400	`PRESS_NOT_READY`	Der Beitrag ist noch nicht bereit (Sprachen, Texte, Bildnachweis); `errors` nennt die Gründe.
403	`PRESS_WRITE_PLATFORM_ONLY`	Der Bereich `presse:write` gibt es nur für Schlüssel der Plattform-Organisation.
404	`NOT_FOUND`	Gibt es nicht — oder die Person darf es nicht sehen (bewusst dieselbe Antwort).
409	`SLUG_TAKEN`	Diese URL-Kennung (slug) ist schon vergeben.
405	`METHOD_NOT_ALLOWED`	MCP-Endpunkt: nur POST (JSON-RPC), kein Server-Stream.
409	`API_KEY_LIMIT`	Höchstzahl aktiver Schlüssel erreicht. Erst einen widerrufen.
429	`RATE_LIMITED`	Zu viele Anfragen. `Retry-After` abwarten.