本文要点
- 新机制只帮助处理刷新响应丢失或未持久化的歧义失败，不替代正确的 token 存储设计。
- 旧 refresh token 可重试到 replacement refresh token 首次被使用为止，但恢复期最多从旧 token 首次使用起算 30 天。
- 30 天恢复期不会延长 refresh token 正常的 90 天生命周期；replacement 一旦使用，旧 token 就退休。
- 每个 shop 的刷新必须串行，access token 与 refresh token 必须作为一对原子保存，后台任务只能读取最新一对。
- 401 invalid_request 是停止重试并重新认证的信号；网络错误、超时、429 或瞬时 5xx 才进入有限重试。
刷新接口成功了，为什么下一轮任务却全部 401
具体场景是：订单或商品同步 worker 发现 access token 即将到期，向 Shopify 刷新成功；但响应回程中断、进程退出，或数据库事务只写入 access token 而漏掉新的 refresh token。日志里可能只剩超时或 5xx，下一轮任务继续拿旧 token，最终收到 401 invalid_request。失败成本不是一次请求，而是整个店铺的后台同步停止、队列反复重试，以及商户被迫重新打开应用。
最危险的错误直觉是同时启动多个 refresh 请求，或者看到 401 就无限重试。正确第一步是按 shop 暂停消费队列，保存状态码、request ID、刷新开始时间和当前 token 记录版本；确认是否有任何 worker 已使用 replacement refresh token，再决定旧 token 是否仍有恢复资格。
旧规则与新规则：60 分钟固定窗口不再是判断依据
旧行为允许已使用的 refresh token 在最多 60 分钟内重试。如果应用没有收到或保存新返回的 access token 与 refresh token，窗口结束后旧 token 无法继续使用，常常只能等商户重新打开应用完成认证。
2026 年 8 月 28 日起，使用 expiring offline access tokens 的应用可以继续重试此前保存的 refresh token，直到开始使用 replacement refresh token。恢复期上限是旧 refresh token 首次使用后的 30 天，而且不会把它正常的 90 天生命周期向后延长。replacement 一旦被使用，前一个 token 立即退休。该变化不需要新 API version、配置或 opt-in。
先判断你是否属于受影响范围
本页适用于调用 Admin GraphQL API 或 Admin REST API、并使用 expiring offline access tokens 的应用，尤其是没有活跃商户会话仍需运行 webhook、订单同步或定时任务的 public app。Shopify 官方 app template 通常会处理刷新，但自建认证层、队列和数据库仍要保证存储一致性。
不使用 expiring offline access tokens 的应用不受此次恢复机制影响。custom app 或 merchant-created app 也不要把 2027 年 public app 强制迁移规则套到自己身上。若问题发生在 online token、client credentials、权限 scope、卸载或 client secret 撤销，应该回到相应认证流程，而不是套用本页的恢复路径。
按 shop 恢复的七步检查表
第一，暂停该 shop 的刷新与依赖任务，避免并发消费同一 token。第二，读取当前 token pair、记录版本、首次刷新时间与过期字段，不要硬编码时长。第三，查日志确认 replacement refresh token 是否已经发起过请求。第四，若只是超时、网络错误或瞬时 5xx，使用数据库里仍保存的旧 refresh token 做一次受控重试。第五，把返回的 access token、refresh token、expires_in 和 refresh_token_expires_in 放进同一数据库事务。第六，以 compare-and-swap 或行锁拒绝旧 worker 覆盖新版本。第七，提交后再恢复该 shop 队列，并用一个只读 Admin API 请求验证。
刷新接口的成功响应不是完成条件，token pair 原子落库才是。建议为每个 shop 保存 token generation 或版本号，让 worker 只能从单一权威记录读取；日志只记录哈希、后四位或版本，禁止写出完整 token。
状态码决策：什么时候重试，什么时候停手
网络连接错误、客户端超时、429 或瞬时 5xx 可以进入有上限且带抖动的重试，并继续使用同一个 refresh token 处理这次歧义失败。若返回 401 Unauthorized 与 invalid_request，Shopify 将未知 token、已过期 token、恢复窗口外重放、应用卸载或撤销等终态统一到同一错误；此时停止自动重试，标记该 shop 需要重新认证。
403 也不能一律当作网络或 refresh token 错误。2027 年 1 月 1 日后，public app 使用 non-expiring offline token 调 Admin API 会收到包含迁移提示的 403；缺少 scope 也可能是 403。应匹配官方错误信息、核 token 类型和 scope，再决定执行 token exchange、重新授权或权限修复。
上线前用故障注入验证，不要拿商户店铺试错
在开发店铺分别模拟四种情况：刷新响应成功后客户端超时、成功响应后事务回滚、两个 worker 同时刷新、replacement 已使用后旧 token 再请求。验收标准是前两种能恢复且最终只有一对 token，第三种被串行锁或版本检查挡住，第四种停止重试并进入重新认证。
发布时先放少量店铺，监控 refresh 成功但落库失败、同 shop 并发冲突、401 invalid_request、重新认证数量和队列积压。任何一项异常上升就停止扩大；回滚应用代码时不得回滚数据库中的新 token pair，否则会把仍有效的 replacement 丢掉。
常见误区与网络边界
误区一是把 30 天当成新的 refresh token 有效期；正常生命周期仍是 90 天，恢复期只是其中的上限。误区二是以为旧 token 与 replacement 可以长期并行使用；replacement 首次使用后旧 token 退休。误区三是每个 worker 各自缓存 token；这会让已经退休的版本反复出现。误区四是遇到 401 就切换出口 IP；认证终态不会因换网络恢复。
只有 DNS、TLS、连接超时或明确的瞬时 5xx 才先参考<a href="/resources/proxy-connection-troubleshooting-checklist">代理连接排查清单</a>处理传输问题。需要稳定运行跨境店铺后台任务时，可<a href="/" target="_blank" rel="noopener noreferrer">访问 PuppyIP 官网</a>了解网络环境；网络只能减少响应丢失，不能替代串行刷新、原子落库和正确的重新认证。
资料来源
常见问题
Shopify 这次 refresh token 变化什么时候发布？
Shopify Developer Changelog 于 2026 年 8 月 28 日发布，适用于使用 expiring offline access tokens 的应用，无需切换 API version、配置或 opt-in。
旧 refresh token 现在能重试多久？
可以重试到 replacement refresh token 首次被使用为止，但恢复期最多从旧 token 首次使用后算 30 天，同时不能超过该 token 正常的 90 天生命周期。
replacement token 已经使用后还能退回旧 token 吗？
不能。replacement refresh token 一旦被使用，前一个 refresh token 就会退休；此时重放旧 token 不属于响应丢失恢复。
401 invalid_request 应该继续重试吗？
不应该自动无限重试。Shopify 把过期、撤销、卸载、未知 token 和恢复窗口外重放等终态统一为该错误，应停止并让商户重新认证。
为什么必须把两个 token 原子保存？
access token 与 refresh token 是同一次轮换返回的一对。只保存其中一个会让后续 API 调用和下一次刷新引用不同代的凭据，造成难以恢复的 401。
换 IP 能解决 refresh token 401 吗？
不能。401 invalid_request 是凭据状态问题；只有超时、DNS、TLS 或瞬时 5xx 等独立证据出现时，才需要另外排查网络链路。