# Autorisations, erreurs et limites

> Le tableau des scopes, le format des erreurs (RFC 9457) avec des codes stables, les limites de débit.

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

## Autorisations (scopes)

Un client demande des autorisations lors de son enregistrement ; le membre les voit sur la page de consentement.

| Scope | Qui | Quoi |
|---|---|---|
| `profile:read` | membre | `GET /v1/me` — nom, e-mail, coordonnées, données de naissance, le code fiscal quand il y en a un, et la façon dont la personne est identifiée (`codicefiscale_check`) |
| `profile:write` | membre | `PATCH /v1/me` — téléphone, genre, et l’identification : date, lieu et pays de naissance, code fiscal (facultatif, peut être ajouté plus tard ; revalidé) |
| `membership:read` | membre | `GET /v1/me/membership`, `/events`, `/statuto`, `/card` |
| `membership:request` | membre | `POST /v1/me/membership` — demande d’adhésion |
| `statuto:accept` | membre | `POST /v1/me/membership/statuto/accept` |
| `network:manage` | membre | le consentement du membre aux circuits (bientôt) |
| `memberships:read` | client | `GET /v1/memberships/{id}/status` |
| `verify:read` | client | vérification des cartes au-delà du quota anonyme |
| `identity:signup` | client | `POST /v1/signup` — créer des comptes au nom des membres ([intégrations serveur](https://developers.vimine.network/fr/guides/server/#faire-adhérer-des-membres-depuis-votre-système)) |
| `enroll:write` | client | `POST /v1/enroll` — envoyer des demandes d’adhésion, avec ou sans code fiscal ([guide](https://developers.vimine.network/fr/guides/members-without-cf/)) |
| `events:read` | membre | `GET /v1/events`, `/v1/events/{slug}`, `/eligibility` — événements réservés aux membres compris ([guide](https://developers.vimine.network/fr/guides/events/)) |
| `registrations:read` | membre, client | `GET /v1/me/registrations` (membre) ; `GET /v1/events/{slug}/registrations` (client, sans données personnelles) |
| `registrations:write` | membre, client | `POST /v1/events/{slug}/registrations` et `DELETE /v1/me/registrations/{id}` (membre) ; `POST …/registrations/guest` (client) |
| `checkins:write` | client | `POST /v1/checkins` — contrôles à l’entrée à partir d’une carte ou d’une inscription |
| `webhooks:manage` | client | bientôt |

Un client public ou natif ne peut demander que des autorisations « membre » ; les autorisations « client » exigent un
client confidentiel. Une personne qui n’est pas encore membre ne peut accorder que les autorisations d’adhésion
(`profile:*`, `membership:read`, `membership:request`, `statuto:accept`).

## Erreurs

Les réponses d’erreur sont en `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` est stable : c’est lui qu’il faut tester. `errors[]` accompagne `validation_failed` et
`identification_required` (`{ field, code }`). Une entrée `codicefiscale_mismatch` — un code fiscal en désaccord avec
les données de naissance de la personne — porte aussi `mismatches`, `hints` et `confirmable` : quand `confirmable` vaut
`true`, la personne peut confirmer le code et la requête est répétée avec `codicefiscale_confirmed: true` (voir
[Membres sans code fiscal](https://developers.vimine.network/fr/guides/members-without-cf/#un-code-en-désaccord-et-la-confirmation)). Les endpoints
OAuth (`/v1/oauth/token`, `/revoke`) répondent au format OAuth (`{ error, error_description }`).

| `code` | Signification |
|---|---|
| `missing_token`, `invalid_token`, `token_expired` | 401 — reconnectez-vous (le SDK rafraîchit et réessaie de lui-même) |
| `insufficient_scope` | 403 — le jeton n’a pas cette autorisation |
| `api_disabled` | 403 — l’association n’a pas activé l’API ou n’accepte pas de demandes |
| `plan_limit` | 403 — la formule de l’association n’a plus de place pour un membre de plus (vérifiez `aps.accepting_requests` avant d’afficher le formulaire) |
| `not_available` | 403 — l’association ne prend pas de demandes en ce moment : elle n’a pas encore accepté les accords de la plateforme ni enregistré son statuto, elle n’est pas prête, ou elle ne prend que les personnes qu’elle a invitées ([la bêta privée](#la-bêta-privée)) ; `detail` dit laquelle de ces raisons. Sur `POST /v1/signup` : pendant la bêta, les comptes sont créés sur invitation |
| `not_found` | 404 — aussi pour les ressources d’autres associations |
| `validation_failed` | 422 — voir `errors[]` (`required`, `invalid`, `invalid_codicefiscale`, `codicefiscale_mismatch` avec `confirmable`…) |
| `identification_required` | 422 sur `POST /v1/me/membership`, 409 sur `POST /v1/enroll/confirm` — la personne n’est pas identifiée : il faut un code fiscal, ou la date, le lieu et le pays de naissance ; `errors[]` nomme ce qui manque |
| `statuto_outdated`, `statuto_required` | 422 — indique la version du statuto en vigueur (`detail`) |
| `rate_limited` | 429 — attendez `Retry-After` |
| `unavailable` | 503 — réessayez dans un instant |

OAuth : `invalid_grant` (code ou jeton de rafraîchissement invalide, expiré ou réutilisé), `invalid_client`,
`invalid_scope`, `unauthorized_client` (client en attente d’activation), `access_denied` (le membre a annulé).

Dans le SDK, tout cela est une [`VimineError`](https://developers.vimine.network/fr/sdk/errors/) avec le même `code`.

## La bêta privée

Vimine est en bêta privée : les personnes et les associations entrent **sur invitation**. Pour un client, cela
signifie :

- `POST /v1/signup` répond `403 not_available` et ne crée rien, sauf si Vimine a ouvert l’adhésion publique de votre
  association ;
- une association qui ne prend que les personnes qu’elle a invitées a `aps.invitation_only: true` et
  `aps.accepting_requests: false` dans son profil public ([`association(slug)`](https://developers.vimine.network/fr/sdk/public/)) ; `POST /v1/enroll` et
  `POST /v1/me/membership` répondent `403 not_available`. Une personne invitée adhère depuis le lien qu’elle reçoit par
  e-mail ;
- les [sandbox](https://developers.vimine.network/fr/guides/sandbox/) restent ouvertes : les clients de test fonctionnent comme toujours.

Vérifiez `aps.accepting_requests` avant d’afficher un formulaire d’adhésion — pour la bêta comme pour tout le reste ;
`<vimine-events>` et `<vimine-enroll>` le font déjà.

## Limites

- Par adresse IP : 60 requêtes/minute sur les endpoints sensibles (vérification des cartes, code fiscal, jeton),
  120/minute sur le reste ; `RateLimit-*` et `Retry-After` dans les réponses.
- `POST /v1/me/membership` accepte `Idempotency-Key` : la même clé dans les 24 heures renvoie la même réponse
  (le SDK en génère une par appel).
- Les réponses authentifiées sont en `Cache-Control: no-store`.
- Chaque réponse porte un `request_id` : citez-le quand vous signalez un problème.