# Permissões, erros e limites

> A tabela de escopos, o formato dos erros (RFC 9457) com códigos estáveis, os limites de requisições.

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

## Permissões (escopos)

Um cliente pede permissões quando é registrado; o associado as vê na página de consentimento.

| Escopo | Quem | O quê |
|---|---|---|
| `profile:read` | associado | `GET /v1/me` — nome, e-mail, contatos, dados de nascimento, o código fiscal quando existe, e como a pessoa está identificada (`codicefiscale_check`) |
| `profile:write` | associado | `PATCH /v1/me` — telefone, sexo, e a identificação: data, local e país de nascimento, código fiscal (opcional, pode ser adicionado depois; validado de novo) |
| `membership:read` | associado | `GET /v1/me/membership`, `/events`, `/statuto`, `/card` |
| `membership:request` | associado | `POST /v1/me/membership` — pedido de adesão |
| `statuto:accept` | associado | `POST /v1/me/membership/statuto/accept` |
| `network:manage` | associado | o consentimento do associado aos circuitos (em breve) |
| `memberships:read` | cliente | `GET /v1/memberships/{id}/status` |
| `verify:read` | cliente | verificação das carteirinhas além da cota anônima |
| `identity:signup` | cliente | `POST /v1/signup` — criar contas em nome dos associados ([integrações de servidor](https://developers.vimine.network/pt/guides/server/#fazer-a-adesão-de-associados-pelo-seu-sistema)) |
| `enroll:write` | cliente | `POST /v1/enroll` — enviar pedidos de adesão, com ou sem código fiscal ([guia](https://developers.vimine.network/pt/guides/members-without-cf/)) |
| `events:read` | associado | `GET /v1/events`, `/v1/events/{slug}`, `/eligibility` — incluindo os eventos só para associados ([guia](https://developers.vimine.network/pt/guides/events/)) |
| `registrations:read` | associado, cliente | `GET /v1/me/registrations` (associado); `GET /v1/events/{slug}/registrations` (cliente, sem dados pessoais) |
| `registrations:write` | associado, cliente | `POST /v1/events/{slug}/registrations` e `DELETE /v1/me/registrations/{id}` (associado); `POST …/registrations/guest` (cliente) |
| `checkins:write` | cliente | `POST /v1/checkins` — check-ins na entrada a partir de uma carteirinha ou de uma inscrição |
| `webhooks:manage` | cliente | em breve |

Um cliente público ou nativo só pode pedir permissões de associado; as permissões de "cliente" exigem um cliente
confidencial. Quem ainda não é associado só pode conceder as permissões de adesão (`profile:*`,
`membership:read`, `membership:request`, `statuto:accept`).

## Erros

As respostas de erro são `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": "…"
}
```

O `code` é estável: tome as suas decisões com base nele. `errors[]` acompanha `validation_failed` e
`identification_required` (`{ field, code }`). Uma entrada `codicefiscale_mismatch` — um código fiscal que não confere
com os dados de nascimento da pessoa — também traz `mismatches`, `hints` e `confirmable`: quando `confirmable` é `true`
a pessoa pode confirmar o código e o pedido é repetido com `codicefiscale_confirmed: true` (veja
[Associados sem código fiscal](https://developers.vimine.network/pt/guides/members-without-cf/#um-código-que-não-confere-e-a-confirmação)). Os
endpoints OAuth (`/v1/oauth/token`, `/revoke`) respondem no formato OAuth (`{ error, error_description }`).

| `code` | Significado |
|---|---|
| `missing_token`, `invalid_token`, `token_expired` | 401 — entre de novo (o SDK renova e repete sozinho) |
| `insufficient_scope` | 403 — falta essa permissão ao token |
| `api_disabled` | 403 — a associação não ativou a API ou não aceita pedidos |
| `plan_limit` | 403 — o plano da associação não tem espaço para mais um associado (verifique `aps.accepting_requests` antes de mostrar o formulário) |
| `not_available` | 403 — a associação não está recebendo pedidos agora: ainda não aceitou os acordos da plataforma ou não registrou o seu statuto, não está pronta, ou só recebe as pessoas que convidou ([o beta privado](#o-beta-privado)); `detail` diz qual é o caso. Em `POST /v1/signup`: durante o beta, as contas são criadas por convite |
| `not_found` | 404 — também para os recursos de outras associações |
| `validation_failed` | 422 — veja `errors[]` (`required`, `invalid`, `invalid_codicefiscale`, `codicefiscale_mismatch` com `confirmable`…) |
| `identification_required` | 422 em `POST /v1/me/membership`, 409 em `POST /v1/enroll/confirm` — a pessoa não está identificada: é preciso um código fiscal, ou data, local e país de nascimento; `errors[]` indica o que falta |
| `statuto_outdated`, `statuto_required` | 422 — indica a versão do statuto em vigor (`detail`) |
| `rate_limited` | 429 — espere `Retry-After` |
| `unavailable` | 503 — tente de novo daqui a pouco |

OAuth: `invalid_grant` (código ou refresh token inválido, vencido ou reutilizado), `invalid_client`, `invalid_scope`,
`unauthorized_client` (cliente aguardando ativação), `access_denied` (o associado cancelou).

No SDK, tudo isso é um [`VimineError`](https://developers.vimine.network/pt/sdk/errors/) com o mesmo `code`.

## O beta privado

O Vimine está em beta privado: pessoas e associações entram **por convite**. Para um cliente, isso quer dizer:

- `POST /v1/signup` responde `403 not_available` e não cria nada, a não ser que o Vimine tenha aberto a adesão pública
  da sua associação;
- uma associação que só recebe as pessoas que convidou tem `aps.invitation_only: true` e
  `aps.accepting_requests: false` no seu perfil público ([`association(slug)`](https://developers.vimine.network/pt/sdk/public/)); `POST /v1/enroll` e
  `POST /v1/me/membership` respondem `403 not_available`. Quem tem um convite se associa pelo link que recebe por e-mail;
- os [sandboxes](https://developers.vimine.network/pt/guides/sandbox/) continuam abertos: os clientes de teste funcionam como sempre.

Verifique `aps.accepting_requests` antes de mostrar um formulário de adesão — para o beta como para todo o resto;
`<vimine-events>` e `<vimine-enroll>` já fazem isso.

## Limites

- Por endereço IP: 60 requisições/minuto nos endpoints sensíveis (verificação das carteirinhas, código fiscal, token),
  120/minuto no resto; `RateLimit-*` e `Retry-After` nas respostas.
- `POST /v1/me/membership` aceita `Idempotency-Key`: a mesma chave dentro de 24 horas devolve a mesma resposta
  (o SDK gera uma por chamada).
- As respostas autenticadas são `Cache-Control: no-store`.
- Toda resposta traz um `request_id`: informe-o quando relatar um problema.