---
title: "Seiten, Filter, Fehler und Limits"
description: "Paginierung, Filter, Zeiten und Zeitzonen, Geldbeträge, Fehlerformat (RFC 9457), Rate-Limits und Versionierung der REST-API"
---

## Seiten

Das Mitgliederverzeichnis und die Liste geleisteter Dienste liefern Seiten:

```json
{
  "items": [ { "userId": "…", "displayName": "Mia", "role": "member", "status": "active", "…": "…" } ],
  "page": 1,
  "itemsPerPage": 25,
  "totalItems": 312,
  "hasMore": true
}
```

- `page` beginnt bei 1 (höchstens 1000), `itemsPerPage` 1–100 (Standard 25).
- `hasMore` sagt, ob es eine weitere Seite gibt – frage so lange `page + 1` ab, bis `hasMore` `false` ist.

Andere Listen sind von Natur aus begrenzt und kommen vollständig als `{ "items": [...] }`: Communities, eigene Rollen, Beitrittsanfragen, Kurse, Freischaltungen, Fortschritt. Termine fragst du für einen **Zeitraum** ab (siehe unten).

## Filter

| Endpunkt | Parameter |
| --- | --- |
| `GET …/members` | `query` (Suche im Namen), `status` (`active`, `muted`, `pending`, `banned`, `left`; ohne Angabe aktive und stummgeschaltete), `sort` (`joined`, `name`, `points`, `active`), `minLevel`, `online`, `ageGroup` (ID einer Altersgruppe oder `unknown`, nur mit eingeschalteten Alters-Tags), `page`, `itemsPerPage` |
| `GET …/events` | `from`, `to` – Zeitraum (ISO 8601 mit Zeitzone, z. B. `2026-11-01T00:00:00+01:00`); Standard Monatsanfang bis drei Monate später, höchstens ein Jahr |
| `GET …/events/{eventId}` | `occurrence` – Beginn eines Termins einer Serie (Wert aus `occurrenceStart`); ohne Angabe der nächste anstehende Termin |
| `GET …/duty-completions` | `status` (`pending`, `confirmed`, `rejected`; ohne Angabe alle), `year` (Kalenderjahr, für das der Dienst zählt), `dutyId`, `eventId` (bei Serien alle Termine), `occurrenceKey` (ein Termin, Wert aus den Einträgen), `userId`, `page`, `itemsPerPage`; neueste Termine zuerst |

Unbekannte Parameter werden ignoriert, ungültige Werte ergeben `422` mit dem Parameter in `violations`.

## Zeiten, Zeitzonen, Geld, IDs

- Zeitpunkte in Antworten sind **ISO 8601 mit Zeitzone**, in UTC: `2026-11-05T18:00:00.000+00:00`.
- Events legst du wie im Kalender mit **Wandzeit** an: `startsAt`/`endsAt` als `YYYY-MM-DDTHH:MM` plus `timezone` (z. B. `Europe/Berlin`). Serien (`recurrence` `weekly`, `monthly` = gleicher Tag im Monat oder `monthly_weekday` = Wochentag des Beginns in bestimmten Wochen) behalten die Uhrzeit über die Zeitumstellung. Bei `monthly_weekday` gibst du in `recurrenceWeeks` die Wochen an – `1` bis `4`, `-1` für den letzten –, z. B. `[1]` für jeden 1. Sonntag oder `[3, -1]` für jeden 3. und letzten Montag; der Beginn muss selbst einer dieser Termine sein (sonst 422).
- Geldbeträge sind ganze Zahlen in **Cent** plus `currency` (z. B. `priceCents: 4900`, `currency: "eur"`).
- IDs sind UUIDs. `userId` ist die Konto-ID eines Mitglieds und in allen Communities gleich.
- Links in die Oberfläche (`profileUrl`, `webUrl`, `avatarUrl`) sind absolute Adressen deiner Installation.
- Alle Felder einer Antwort sind immer vorhanden; fehlende Werte sind `null`.

## Fehler

Fehler kommen als **Problem Details** nach RFC 9457 (`Content-Type: application/problem+json`):

```json
{
  "type": "urn:problem:validation-failed",
  "title": "Die Eingaben sind ungültig.",
  "status": 422,
  "instance": "/api/rest/v1/communities/mein-verein/events",
  "violations": [
    { "propertyPath": "startsAt", "message": "Format YYYY-MM-DDTHH:MM.", "code": "…" }
  ]
}
```

| Status | `type` | Bedeutung |
| --- | --- | --- |
| 400 | `urn:problem:bad-request` | Body ist kein gültiges JSON |
| 401 | `urn:problem:unauthenticated` | Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen (mit `WWW-Authenticate: Bearer`) |
| 403 | `urn:problem:forbidden` | Das Konto darf die Community nicht (mehr) verwalten, der Schlüssel darf nur lesen, oder die Rangfolge erlaubt die Aktion nicht |
| 404 | `urn:problem:not-found` | Community, Mitglied, Event, Kurs, Rolle, Formular oder geleisteten Dienst gibt es nicht – oder es gehört zu einer anderen Community |
| 409 | `urn:problem:conflict` | Fachlich nicht möglich, z. B. Anfrage wartet nicht mehr, Mitglied ist nicht aktiv, Zeitraum zu lang; `detail` erklärt den Grund |
| 415 | `urn:problem:unsupported-media-type` | Body ohne `Content-Type: application/json` |
| 422 | `urn:problem:validation-failed` | Eingaben oder Query-Parameter ungültig, siehe `violations` |
| 429 | `urn:problem:rate-limited` | Limit erreicht, siehe `Retry-After` |
| 503 | `urn:problem:maintenance` | Die Installation ist im Wartungsmodus |

`title` und `detail` kommen auf Deutsch oder Englisch – nach der Sprache des Kontos bzw. `Accept-Language`. Werte für Programme sind `status` und `type`, nicht der Text.

## Limits

Je API-Schlüssel gelten **300 lesende Aufrufe** (`GET`) und **60 schreibende Aufrufe** (`POST`, `PUT`, `DELETE`) pro Minute. Jede Antwort trägt `X-RateLimit-Limit` und `X-RateLimit-Remaining`; beim Überschreiten kommt `429` mit `Retry-After` (Sekunden). Warte dann mindestens so lange, bevor du es erneut versuchst. Für große Abgleiche lohnt `itemsPerPage=100`.

## Doppelte Aufrufe vermeiden

Schickst du bei einem `POST` die Kopfzeile `Idempotency-Key` mit (z. B. eine UUID je Vorgang), liefert QuickTribe bei einer Wiederholung mit demselben Wert die erste Antwort erneut, statt die Aktion ein zweites Mal auszuführen (erkennbar an `Idempotent-Replayed: true`). Das hilft bei Netzwerkabbrüchen, etwa beim Anlegen von Events.

## Versionierung

Die Version steht im Pfad (`/api/rest/v1/`). Innerhalb von v1 kommen höchstens **neue** Endpunkte und **neue Felder** in Antworten hinzu – ignoriere unbekannte Felder. Umbenennen oder Entfernen gibt es nur mit einer neuen Version (`/v2/`), die eine Zeit lang parallel läuft. Änderungen stehen in den [Änderungen](/changelog).
