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が返る
• 開発者ヘルプトップへ戻る