# 權限、錯誤與限制

> scope 一覽表、帶穩定錯誤碼的錯誤格式（RFC 9457）、速率限制。

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

## 權限（scope）

用戶端在登記時申請權限；會員在授權同意頁面上看到這些權限。

| Scope | 對象 | 內容 |
|---|---|---|
| `profile:read` | 會員 | `GET /v1/me`——姓名、電子郵件地址、聯絡方式、出生資訊、稅號（如有），以及當事人的身份識別方式（`codicefiscale_check`） |
| `profile:write` | 會員 | `PATCH /v1/me`——電話、性別，以及身份識別資訊：出生日期、出生地和出生國、稅號（可選，可以之後再補充；會重新驗證） |
| `membership:read` | 會員 | `GET /v1/me/membership`、`/events`、`/statuto`、`/card` |
| `membership:request` | 會員 | `POST /v1/me/membership`——入會申請 |
| `statuto:accept` | 會員 | `POST /v1/me/membership/statuto/accept` |
| `network:manage` | 會員 | 會員對加入網路的同意（即將推出） |
| `memberships:read` | 用戶端 | `GET /v1/memberships/{id}/status` |
| `verify:read` | 用戶端 | 超出匿名配額的會員卡核驗 |
| `identity:signup` | 用戶端 | `POST /v1/signup`——代表會員建立帳戶（[伺服器整合](https://developers.vimine.network/zh-hant/guides/server/#從您的系統為會員辦理入會)） |
| `enroll:write` | 用戶端 | `POST /v1/enroll`——提交入會申請，有無稅號均可（[指南](https://developers.vimine.network/zh-hant/guides/members-without-cf/)） |
| `events:read` | 會員 | `GET /v1/events`、`/v1/events/{slug}`、`/eligibility`——包括僅限會員的活動（[指南](https://developers.vimine.network/zh-hant/guides/events/)） |
| `registrations:read` | 會員、用戶端 | `GET /v1/me/registrations`（會員）；`GET /v1/events/{slug}/registrations`（用戶端，不含個人資料） |
| `registrations:write` | 會員、用戶端 | `POST /v1/events/{slug}/registrations` 和 `DELETE /v1/me/registrations/{id}`（會員）；`POST …/registrations/guest`（用戶端） |
| `checkins:write` | 用戶端 | `POST /v1/checkins`——憑會員卡或報名辦理入場登記 |
| `webhooks:manage` | 用戶端 | 即將推出 |

公開用戶端或原生用戶端只能申請會員權限；“用戶端”權限需要機密用戶端。尚未入會的人只能授予入會相關的權限（`profile:*`、`membership:read`、`membership:request`、`statuto:accept`）。

## 錯誤

錯誤回應為 `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` 是穩定的：請以它作為分支依據。`errors[]` 隨 `validation_failed` 和 `identification_required` 一起傳回（`{ field, code }`）。`codicefiscale_mismatch` 記錄——稅號與當事人的出生資訊不一致——還帶有 `mismatches`、`hints` 和 `confirmable`：當 `confirmable` 為 `true` 時，當事人可以確認該稅號，並帶上 `codicefiscale_confirmed: true` 重複請求（參見[沒有義大利稅號的會員](https://developers.vimine.network/zh-hant/guides/members-without-cf/#不一致的稅號與確認)）。OAuth 端點（`/v1/oauth/token`、`/revoke`）以 OAuth 格式傳回（`{ error, error_description }`）。

| `code` | 含義 |
|---|---|
| `missing_token`、`invalid_token`、`token_expired` | 401——請重新登入（SDK 會自動重新整理並重試） |
| `insufficient_scope` | 403——權杖缺少該權限 |
| `api_disabled` | 403——協會未開通 API，或不接受申請 |
| `plan_limit` | 403——協會的方案已容納不下更多會員（顯示表單前請先檢查 `aps.accepting_requests`） |
| `not_available` | 403——協會目前不接受申請：尚未接受平臺協議或尚未登記章程、尚未準備就緒，或只接納受邀請的人（[內測](#內測)）；`detail` 會說明是哪種情況。在 `POST /v1/signup` 上：內測期間帳戶只能憑邀請建立 |
| `not_found` | 404——其他協會的資源也傳回此錯誤 |
| `validation_failed` | 422——參見 `errors[]`（`required`、`invalid`、`invalid_codicefiscale`、帶 `confirmable` 的 `codicefiscale_mismatch`…） |
| `identification_required` | 在 `POST /v1/me/membership` 上為 422，在 `POST /v1/enroll/confirm` 上為 409——當事人尚未識別身份：需要稅號，或出生日期、出生地和出生國；`errors[]` 列出缺少的內容 |
| `statuto_outdated`、`statuto_required` | 422——指明現行章程的版本（`detail`） |
| `rate_limited` | 429——請等待 `Retry-After` |
| `unavailable` | 503——請稍後重試 |

OAuth：`invalid_grant`（授權碼或重新整理權杖無效、已過期或被重複使用）、`invalid_client`、`invalid_scope`、`unauthorized_client`（用戶端等待開通）、`access_denied`（會員已取消）。

在 SDK 中，以上所有錯誤都是帶有相同 `code` 的 [`VimineError`](https://developers.vimine.network/zh-hant/sdk/errors/)。

## 內測

Vimine 正處於內測階段：個人和協會都**憑邀請**加入。對用戶端而言，這意味著：

- `POST /v1/signup` 傳回 `403 not_available`，不建立任何內容，除非 Vimine 已為您的協會開放公開入會；
- 只接納受邀請者的協會，其公開資料中帶有 `aps.invitation_only: true` 和 `aps.accepting_requests: false`（[`association(slug)`](https://developers.vimine.network/zh-hant/sdk/public/)）；`POST /v1/enroll` 和 `POST /v1/me/membership` 傳回 `403 not_available`。受到邀請的人透過郵件中收到的連結入會；
- [沙箱](https://developers.vimine.network/zh-hant/guides/sandbox/)保持開放：測試用戶端照常工作。

顯示入會表單之前，請先檢查 `aps.accepting_requests`——內測期間如此，其他情況也一樣；`<vimine-events>` 和 `<vimine-enroll>` 已經這樣做了。

## 限制

- 按 IP 位址計：敏感端點（會員卡核驗、稅號、權杖）每分鐘 60 次請求，其餘端點每分鐘 120 次；回應中帶有 `RateLimit-*` 和 `Retry-After`。
- `POST /v1/me/membership` 接受 `Idempotency-Key`：24 小時內使用相同的鍵會傳回相同的回應（SDK 會為每次呼叫產生一個）。
- 經過驗證的回應為 `Cache-Control: no-store`。
- 每個回應都帶有 `request_id`：報告問題時請註明它。