Developers Limits and errors

Limits and error codes

Limits of the CLUP.life API (requests per minute, keys, webhooks) and all error codes with meaning and remedy.

Limits#

Limit	Basic (personal key)	Premium (organization key)
Requests per minute and key	60	600
Active keys	3	20
Webhooks per organization	—	10
Longest validity of a key	365 days	365 days

Limiting applies per key in a sliding one-minute window; the general limit per IP address and route applies on top. When exceeded the API answers 429 RATE_LIMITED with the Retry-After header (seconds). Event periods are limited to 400 days, lists to 100 entries per page.

Tips: use cursor pages with limit=100 instead of many small calls, cache results (websites 5–15 minutes) and use webhooks for changes instead of constant polling.

Error format#

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

Rely on code (stable), not on the wording of message (German, may change). For validation errors errors names the affected fields.

Error codes#

Status	Code	Meaning and remedy
400	`VALIDATION_FAILED`	Input invalid; `errors` names the fields.
401	`INVALID_API_KEY`	Key wrong, expired, revoked, or the account is blocked.
403	`INSUFFICIENT_SCOPE`	The key lacks the scope for this route. Create a new key with more scopes.
403	`API_KEY_NOT_ALLOWED`	This route cannot be reached with any key (account, finance, children, administration).
403	`PREMIUM_REQUIRED`	Organization keys, writing and webhooks need Premium for the organization.
403	`FORBIDDEN`	The person behind the key lacks the right for this.
403	`ADULT_ONLY`	Only adult accounts can create keys.
403	`WRITE_NEEDS_ORGANIZATION`	Write scopes exist only for organization keys.
403	`ORGANIZATION_KEY_REQUIRED`	Write calls need a key bound to an organization.
403	`RANGE_INVALID`	The period must run forward and cover at most 400 days.
400	`PRESS_NOT_READY`	The post is not ready yet (languages, texts, image credit); `errors` lists the reasons.
403	`PRESS_WRITE_PLATFORM_ONLY`	The scope `presse:write` exists only for keys of the platform organization.
404	`NOT_FOUND`	Does not exist — or the person may not see it (deliberately the same answer).
409	`SLUG_TAKEN`	This slug is already taken.
405	`METHOD_NOT_ALLOWED`	MCP endpoint: POST only (JSON-RPC), no server stream.
409	`API_KEY_LIMIT`	Maximum number of active keys reached. Revoke one first.
429	`RATE_LIMITED`	Too many requests. Wait for `Retry-After`.