# Berechtigungen, Fehler und Limits

> Die Scope-Tabelle, das Fehlerformat (RFC 9457) mit stabilen Codes, die Ratenlimits.

URL: https://developers.vimine.network/de/guides/scopes-and-errors/

## Berechtigungen (Scopes)

Ein Client fordert Berechtigungen an, wenn er registriert wird; das Mitglied sieht sie auf der Einwilligungsseite.

| Scope | Wer | Was |
|---|---|---|
| `profile:read` | Mitglied | `GET /v1/me` — Name, E-Mail, Kontaktdaten, Geburtsdaten, die Steuernummer, falls vorhanden, und wie die Person identifiziert ist (`codicefiscale_check`) |
| `profile:write` | Mitglied | `PATCH /v1/me` — Telefon, Geschlecht und die Identifizierung: Geburtsdatum, Geburtsort und Geburtsland, Steuernummer (optional, kann später ergänzt werden; wird erneut geprüft) |
| `membership:read` | Mitglied | `GET /v1/me/membership`, `/events`, `/statuto`, `/card` |
| `membership:request` | Mitglied | `POST /v1/me/membership` — Beitrittsantrag |
| `statuto:accept` | Mitglied | `POST /v1/me/membership/statuto/accept` |
| `network:manage` | Mitglied | die Einwilligung des Mitglieds in Verbünde (demnächst) |
| `memberships:read` | Client | `GET /v1/memberships/{id}/status` |
| `verify:read` | Client | Ausweisprüfung über das anonyme Kontingent hinaus |
| `identity:signup` | Client | `POST /v1/signup` — Konten im Namen von Mitgliedern anlegen ([Server-Integrationen](https://developers.vimine.network/de/guides/server/#beitritte-aus-ihrem-system)) |
| `enroll:write` | Client | `POST /v1/enroll` — Beitrittsanträge stellen, mit oder ohne Steuernummer ([Anleitung](https://developers.vimine.network/de/guides/members-without-cf/)) |
| `events:read` | Mitglied | `GET /v1/events`, `/v1/events/{slug}`, `/eligibility` — einschließlich Veranstaltungen nur für Mitglieder ([Anleitung](https://developers.vimine.network/de/guides/events/)) |
| `registrations:read` | Mitglied, Client | `GET /v1/me/registrations` (Mitglied); `GET /v1/events/{slug}/registrations` (Client, ohne personenbezogene Daten) |
| `registrations:write` | Mitglied, Client | `POST /v1/events/{slug}/registrations` und `DELETE /v1/me/registrations/{id}` (Mitglied); `POST …/registrations/guest` (Client) |
| `checkins:write` | Client | `POST /v1/checkins` — Check-ins am Einlass, von einem Ausweis oder einer Anmeldung |
| `webhooks:manage` | Client | demnächst |

Ein öffentlicher oder nativer Client darf nur Mitglieder-Berechtigungen anfordern; „Client“-Berechtigungen erfordern einen vertraulichen
Client. Wer noch nicht Mitglied ist, darf nur die Beitrittsberechtigungen erteilen (`profile:*`,
`membership:read`, `membership:request`, `statuto:accept`).

## Fehler

Fehlerantworten sind `application/problem+json` (RFC 9457):

```json
{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}
```

`code` ist stabil: Verzweigen Sie danach. `errors[]` begleitet `validation_failed` und `identification_required`
(`{ field, code }`). Ein Eintrag `codicefiscale_mismatch` — eine Steuernummer, die nicht zu den Geburtsdaten der Person passt —
enthält außerdem `mismatches`, `hints` und `confirmable`: Ist `confirmable` gleich `true`, darf die Person die Steuernummer bestätigen, und
der Antrag wird mit `codicefiscale_confirmed: true` wiederholt (siehe
[Mitglieder ohne Steuernummer](https://developers.vimine.network/de/guides/members-without-cf/#eine-abweichende-steuernummer-und-die-bestätigung)). Die OAuth-Endpunkte
(`/v1/oauth/token`, `/revoke`) antworten im OAuth-Format (`{ error, error_description }`).

| `code` | Bedeutung |
|---|---|
| `missing_token`, `invalid_token`, `token_expired` | 401 — neu anmelden (das SDK erneuert und wiederholt selbst) |
| `insufficient_scope` | 403 — dem Token fehlt diese Berechtigung |
| `api_disabled` | 403 — der Verein hat die API nicht aktiviert oder nimmt keine Anträge an |
| `plan_limit` | 403 — der Tarif des Vereins hat keinen Platz für ein weiteres Mitglied (prüfen Sie `aps.accepting_requests`, bevor Sie das Formular zeigen) |
| `not_available` | 403 — der Verein nimmt gerade keine Anträge an: Er hat die Verträge der Plattform noch nicht akzeptiert oder sein Statuto noch nicht hinterlegt, er ist nicht bereit, oder er nimmt nur Personen auf, die er eingeladen hat ([die private Beta](#die-private-beta)); `detail` sagt, was zutrifft. Bei `POST /v1/signup`: Während der Beta werden Konten auf Einladung angelegt |
| `not_found` | 404 — auch für Ressourcen anderer Vereine |
| `validation_failed` | 422 — siehe `errors[]` (`required`, `invalid`, `invalid_codicefiscale`, `codicefiscale_mismatch` mit `confirmable`…) |
| `identification_required` | 422 bei `POST /v1/me/membership`, 409 bei `POST /v1/enroll/confirm` — die Person ist nicht identifiziert: Eine Steuernummer oder Geburtsdatum, Geburtsort und Geburtsland sind nötig; `errors[]` nennt, was fehlt |
| `statuto_outdated`, `statuto_required` | 422 — nennt die geltende Version des Statuto (`detail`) |
| `rate_limited` | 429 — `Retry-After` abwarten |
| `unavailable` | 503 — in Kürze erneut versuchen |

OAuth: `invalid_grant` (Code oder Refresh-Token ungültig, abgelaufen oder wiederverwendet), `invalid_client`, `invalid_scope`,
`unauthorized_client` (Client wartet auf Aktivierung), `access_denied` (das Mitglied hat abgebrochen).

Im SDK ist all das ein [`VimineError`](https://developers.vimine.network/de/sdk/errors/) mit demselben `code`.

## Die private Beta

Vimine ist in einer privaten Beta: Personen und Vereine kommen **auf Einladung** herein. Für einen Client bedeutet das:

- `POST /v1/signup` antwortet `403 not_available` und legt nichts an, es sei denn, Vimine hat den öffentlichen Beitritt
  Ihres Vereins geöffnet;
- ein Verein, der nur Personen aufnimmt, die er eingeladen hat, hat `aps.invitation_only: true` und
  `aps.accepting_requests: false` in seinem öffentlichen Profil ([`association(slug)`](https://developers.vimine.network/de/sdk/public/)); `POST /v1/enroll` und
  `POST /v1/me/membership` antworten `403 not_available`. Wer eine Einladung hat, tritt über den Link bei, den er per E-Mail erhält;
- die [Sandboxes](https://developers.vimine.network/de/guides/sandbox/) bleiben offen: Test-Clients funktionieren wie immer.

Prüfen Sie `aps.accepting_requests`, bevor Sie ein Beitrittsformular zeigen — für die Beta wie für alles andere;
`<vimine-events>` und `<vimine-enroll>` tun das bereits.

## Limits

- Pro IP-Adresse: 60 Anfragen/Minute auf den sensiblen Endpunkten (Ausweisprüfung, Steuernummer, Token),
  120/Minute auf den übrigen; `RateLimit-*` und `Retry-After` in den Antworten.
- `POST /v1/me/membership` akzeptiert `Idempotency-Key`: Derselbe Schlüssel innerhalb von 24 Stunden liefert dieselbe Antwort
  (das SDK erzeugt einen pro Aufruf).
- Authentifizierte Antworten sind `Cache-Control: no-store`.
- Jede Antwort trägt eine `request_id`: Nennen Sie sie, wenn Sie ein Problem melden.