Concepts

Errors

Every error is an application/problem+json body (RFC 9457). The type URI links to the matching section on this page — match on the last path segment, the error code.

{
  "type": "https://developers.club-tool.nl/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key lacks the required scope: members:write.",
  "required_scope": "members:write"
}

detail is for humans and may be localized (Dutch) when it comes from domain validation. Branch on status and the type code — those are stable contract.

Error code catalogue

Code	Status	Meaning
`bad_request`	400	Malformed parameter or request body (e.g. invalid `limit` or date).
`validation_failed`	400	The body was readable but domain validation rejected it (missing name, unknown field, invalid status…).
`idempotency_key_required`	400	Bulk endpoints require an `Idempotency-Key` header.
`unauthenticated`	401	Missing, unknown, revoked or expired API key.
`forbidden`	403	The request is authenticated but not allowed.
`insufficient_scope`	403	The key lacks the required scope; see `required_scope`.
`upgrade_required`	403	The club is not on the Pro plan. Keys are blocked, not deleted.
`plan_expired`	403	The club's subscription expired: reads still work, writes are blocked.
`demo_read_only`	403	The demo club is read-only.
`not_found`	404	The resource does not exist — or belongs to another club (deliberately indistinguishable).
`method_not_allowed`	405	The path exists but not with this HTTP method.
`conflict`	409	State conflict (e.g. duplicate registration).
`idempotency_key_reuse`	409	The `Idempotency-Key` was already used with a different body.
`payload_too_large`	413	Too many items in one bulk request (max 100).
`rate_limit_exceeded`	429	Rate limit hit — back off and honour `Retry-After`. See rate limits.
`internal_error`	500	Unexpected server error. Retry with backoff; report persistent cases.

Bulk: per-item errors

Bulk endpoints answer 200 with a per-item results array; failed items carry their own status and message there. See bulk & idempotency.