回傳 403/401（權限、權限範圍）

401 與 403 的差異

401 的典型情況與因應

• 權杖過期（expired_token）→ 以刷新權杖更新
• 權杖已撤銷（使用者解除串接等）→ 重新授權流程
• Authorization 標頭的格式不正確 → Bearer （帶半形空格）＋ 權杖
• 環境搞錯（將正式權杖用於測試環境）→ 確認環境

403 的典型情況與因應

• 權限範圍不足（insufficient_scope）→ 追加必要的權限範圍後重新授權
• 無店鋪存取權 → 確認是否未存取應用程式所串接店鋪以外的資源
• User 系權限範圍未審查（app_not_approved）→ 申請審查（參閱另一篇文章）
• 角色權限不足 → 串接時的使用者未持有必要的角色（擁有者等）
• 方案限制（plan_limit_exceeded）→ 升級店鋪端的方案

釐清步驟

1. 確認回應的 error.code 與 message
2. 將 X-RR-Request-Id 記錄至日誌
3. 若為 401 則呼叫 /v1/me 確認權杖本身的有效性（若成功則權杖 OK，若在後段變成 403 則為權限問題）
4. 若為 403，確認目前權杖中包含的 scope（/v1/oauth/introspect）
5. 若未包含必要的權限範圍則重新授權

權限範圍的確認方法

curl -X POST https://receiptroller.io/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=$ACCESS_TOKEN&client_id=$CLIENT_ID&client_secret=$SECRET"

→ {
  "active": true,
  "scope": "store.read receipt.read",
  "client_id": "...",
  "exp": 1745740001
}

相關指南

• OAuth 權限範圍一覽
• User 系權限範圍回傳 app_not_approved
• 返回開發者幫助中心