Shopify Admin API 403 权限不足怎么排查

症状记录#

403 伴随缺 scope 时，看错误里提到的 access scope 名称。需要注意，在应用配置中勾选对应 Admin API 范围并让商家重新安装或更新授权。需要注意，读产品与写产品是不同 scope，只读令牌调用 mutation 会 403。

根因分层#

版本化 API 下 scope 名称以当前版本文档为准。然后，自定义应用的 scope 在后台应用设置里改完要保存并轮换令牌。然后，用 accessToken 的 token 信息接口或文档对照表核对已授范围。

处置办法#

1. 不要把 Storefront 的 unauthenticated 范围拿来调 Admin。
2. 权限变更后旧会话可能仍缓存，重启服务再测。
3. 记录完整 GraphQL 错误扩展字段。
4. 最小权限原则：只开用到的 scope。

通过标准#

验收：缺 scope 时错误可读，补齐后同一 mutation 成功。完成前，把 scope 清单写入应用 README。