Shopify Admin API
Admin API 的报错信息往往只给状态码不给原因，实际排查要从令牌类型、access scope、资源 GID 与调用成本四个维度切入。本分类按 401、403、404、422 与限流五类响应拆解，说明每一类应该先看哪个字段、如何用 GraphQL 查询复现，以及批量写入时如何控制成本。
-
01
Access token 加了 Bearer 前缀导致 401
Postman 里调通的请求搬到代码后全部返回 401……
-
02
Shopify Admin API 401 错误排查指南
401 表示未通过身份验证，优先查 access token 是否过期或未放入 Authorization 头。
-
03
Shopify Admin API 403 权限不足怎么排查
403 伴随缺 scope 时，看错误里提到的 access scope 名称。
-
04
Shopify Admin API 404 找不到资源怎么查
404 常因 GID 或旧 REST 数字 ID 指错店铺或资源已删。
-
05
Shopify Admin API 422 与 userErrors 解读
422 时读 userErrors 数组，不要只看 HTTP 状态。
-
06
Shopify Admin API 偶发 502/504 要不要重试
批量任务日志里零星出现 502 Bad Gateway 或 504，重跑又成功，不确定是否是自身问题。
-
07
Shopify 批量修改上千商品用哪种 API
循环调用 productUpdate 改 2000 个商品，跑了两个小时还触发限流。
-
08
多个进程同时更新商品导致数据被覆盖怎么办
库存同步任务与人工编辑同时改商品，后写入的把前者的改动冲掉，标题或价格莫名回退。
-
09
Admin API 创建商品后库存无法设置怎么办
新商品创建成功，调用 inventorySetQuantities 报「inventory item not fou……
-
10
Admin API 写 metafield 报 invalid value 怎么办
metafieldsSet 返回 INVALID_VALUE，同一个 key 在后台手工能填。
-
11
管理多个 Shopify 店铺的 access token 怎么存
服务商同时服务多个商家店铺，token 混用导致 A 店的订单写进了 B 店，或频繁 401。
-
12
Shopify 应用怎么拿到长期可用的 offline token
应用后台任务运行几小时后全部 401，重新进入应用又恢复，怀疑 token 过期。
-
13
Admin API 修改已下单订单的商品怎么做
需要给订单加一件商品或改数量，直接改 lineItems 报错，提示订单不可编辑。
-
14
Admin API 分页 cursor 用错导致数据重复或漏读
同步商品或订单时，总数对不上：有的记录被处理两次，有的整页被跳过……
-
15
Admin API 查顾客信息被拒怎么申请权限
查询 customers 或订单里的邮箱、电话返回空，或报未授权访问受保护客户数据。
-
16
Admin API 上传商品图片失败怎么排查
调用 productCreateMedia 报错或图片一直处于 processing，前台不显示。
-
17
Shopify Admin GraphQL 报 THROTTLED 怎么控制查询成本
一次查询多个商品及其变体、图片、metafields，返回 THROTTLED，重试后仍然失败。
-
18
Shopify mutation 返回 200 但数据没变怎么查
创建/更新商品的 mutation 返回 HTTP 200，业务代码当成功处理，实际后台没有任何变化。
-
19
2026-10 升级后订单改地址税费被重算
版本从 2026-07 提到 2026-10 后三处同时出问题：改过收货地址的订单税额变化……
-
20
Shopify API 版本升级后接口报错怎么排查
把 api_version 从旧版本改到新版本后，部分接口开始返回 400 或字段为空，回滚版本又恢复正常。
-
21
API 版本写在 URL 还是请求头才生效
在请求头加了 X-Shopify-API-Version: 2026-10，响应头返回的仍是 2026-07……
-
22
App Proxy 签名校验失败一直被 403 怎么排
前台访问 /apps/reviews 时接口返回 403，日志里是自己代码抛的 Invalid signature……
-
23
批量 mutation 失败行怎么用 __lineNumber 定位
五千行的批量改价任务完成后，结果文件里大多数行成功，少数行只有 errors，找不到对应输入的第几条……
-
24
批量 mutation 上传 JSONL 后启动失败怎么查
stagedUploadsCreate 已经返回了 url，但把 JSONL POST 上去得到 400……
-
25
Shopify Bulk Operation 一直 running 不结束怎么办
发起批量导出后，currentBulkOperation 长时间停留在 RUNNING，超过一小时仍未完成……
-
26
Bulk Operation 完成后 URL 七天过期下载失败
一周前跑完的导出任务，今天点下载返回 403，响应体是一段 XML 而不是 JSONL……
-
27
自定义应用 token 和 OAuth token 能混用吗
后台 Develop apps 里生成的 token 在服务里能跑……
-
28
履约 mutation 报 invalid id 怎么排查
调用 fulfillmentCreateV2 标记发货，userErrors 返回 invalid id……
-
29
GraphQL 游标分页 endCursor 不变导致死循环
全量同步商品的脚本跑了一夜没结束，日志里每页打印的都是同一批 ID，pageInfo.endCursor 每次相同……
-
30
GraphQL mutation 重试后订单重复怎么防
网络超时后重发同一笔退款和同一笔订单，Shopify 侧出现两条记录，对账金额翻倍；日志里两次请求的参数完全一样。
-
31
单次查询 requestedQueryCost 超过 1000 被拒
查询商品并带 variants、metafields、media 时……
-
32
userErrors 和顶层 errors 到底先看哪个
调用 productCreate 返回 200……
-
33
库存调整 mutation 的 changes 写法与幂等键
想把库存从 10 调到 14，调用后后台显示 18……
-
34
metafield 超过 10000 字节读出来是 null
后台能看到完整 JSON，Admin API 也能查到 value……
-
35
metafieldsSet 不传 type 直接写入失败
调 metafieldsSet 只传 ownerId、namespace、key、value……
-
36
orderCreate 传了 PAID 但订单没有交易记录
用 orderCreate 导入历史订单并传 financialStatus: PAID，后台显示已付款……
-
37
部分履约后再次发货报 unfulfillable 怎么办
订单有三件商品，先发一件后订单仍显示 Unfulfilled，第二次发货又报 unfulfillable……
-
38
并发写同一商品报 product 正在被修改
库存同步与人工改价同时进行，mutation 的 userErrors 返回 This product is cur……
-
39
productSet 全量同步把没传的变体删掉了
用 productSet 只提交标题和价格做同步，跑完后商品的 tags……
-
40
REST 迁到 GraphQL 后字段缺失怎么补
按旧文档改完接口，返回里找不到原来 REST 就有的字段（如库存、图片地址、折扣明细），查询直接被拒。
