Shopify MCP报422？Token层只读调用也要买家IP

只读也要买家IP，但不是所有MCP请求都要

Token层指使用Shopify签发凭据识别代理的请求。它向商家UCP MCP端点发送每个tools/call时，必须带Shopify-Buyer-IP，值为所代表买家的真实IPv4或IPv6；get_cart、get_order等只读调用同样适用。

规则覆盖商家端点的Storefront Catalog、Cart、Checkout和Order工具。Global Catalog请求不需要这个头；initialize、tools/list等发现请求也不需要，Signed与Anonymous层同样属于例外。先确认调用对象与身份层，别把一条规则套到所有请求。

这里讨论的是服务端UCP MCP调用，不是买家当前浏览器标签页里的Checkout WebMCP。文档没有为这条header规则列出新的地区、套餐收费或统一切换日，不能把10月9日补文档理解成所有商家当日发生相同迁移。

422先检查实际HTTP请求，别只改工具参数

第一步，确认失败的是Token层商家tools/call，再查看实际发出的HTTP请求头是否包含Shopify-Buyer-IP。只在工具参数或上层对象里写了买家信息，不等于这条header已经随请求发送。

第二步，检查值是否为有效的买家IPv4或IPv6。官方给出的缺少或无效IP拒绝状态是HTTP 422，示例中出现AuthenticationFailed与Missing required buyer IP header；不要把这类拒绝先诊断为限流。

第三步，修正对应请求层后，继续区分返回的错误与所需权限。header补齐只解决这一项条件，不能据此保证购物车、结账或订单调用一定成功；排查记录也应避免保存访问凭据与完整买家敏感信息。

没有买家IP时，服务器出口不能代替

文档明确没有占位值，Shopify也不会退回采用代理连接它时的地址。这里需要的是代理所代表的买家IP，不是为了让字段看起来有效而随便填一个IP；换服务器或网络出口不能补足缺失的买家上下文。

假设一项后台定时任务没有当前买家，却准备用Token层调用商家工具。官方明确这种调用会失败。这个例子用于解释边界，没有执行真实请求；开发者应重新评估任务设计，不能为定时任务编造买家IP。

header、购买权限与订单权限是三件事

Token层要调用complete_checkout，凭据还必须获得完成购买的权限。读取订单的get_order需要read_global_api_orders范围，而且订单访问限定为经该代理下单的订单；有买家IP不等于可以读取店铺全部订单。

Signed层用UCP规范的HTTP消息签名识别代理，Anonymous层没有凭据或签名。它们可以使用相应目录、购物车及结账构建或编辑工具，但不能complete_checkout，也不能访问Order工具；不要把不需要buyer-IP误读成权限更宽。

429按Retry-After等待，别把每秒5次当全站额度

超过当前身份层的限额时，Shopify返回HTTP 429及Retry-After。商家MCP额度会因身份层和工具而异，也可能调整；应按响应要求等待，再使用指数退避与随机抖动，而不是硬编码一个所有工具通用的请求预算。

已认证Global Catalog默认是每个API客户端每秒5次，search_catalog、get_product、lookup_catalog共用额度。Storefront Catalog按商家分别限流；未认证流量按IP限流并共享其他未认证流量的限额，吞吐没有保证，官方不建议将它用于生产流量。

重试接受幂等键的操作时，例如complete_checkout，应复用原请求的幂等键，避免把重试变成另一笔动作。Checkout MCP每层的限制都比Cart MCP更严格；可用Cart整理商品行和估算，再为准备购买的买家进入Checkout。

10月9日补了文档，不等于所有报错都修好了

Shopify社区员工Gil-Shopify于2026年10月9日17:04:09 UTC回复，称文档已覆盖buyer-IP要求，并链接到这份Auth and rate limiting说明。新增价值是请求与身份边界写清楚了，不是承诺所有历史错误都已消失。

同一帖子中，早前有人报告给POST添加header后成功，也有人仍在create_cart遇到错误并猜测与密码保护商店有关。这些是个别使用者的结果与问题，不能当作全平台修复或已确定原因；先按当前文档定位请求，再处理剩余错误。