← 技术博客

快递查不到轨迹怎么办？按原因逐一排查

2026-07-26 · 阅读约 6 分钟

「明明发货了，为什么快递查不到？」这是查询接口接入后最常收到的疑问。 「查询不到轨迹」其实包含好几种完全不同的情况：有的是包裹刚发、信息还没上网； 有的是运单号或快递公司填错了；还有的是接口确实查到了、但对方暂时没返回任何节点。 原因不同，处理方式也不同。本文按原因逐一排查，帮你（无论是普通用户还是开发者）快速定位。

一、先分清「报错」还是「查到了但没轨迹」

排查第一步，是看接口返回的是哪一类。成功但轨迹为空和直接报错是两回事：

• success: true 但 progresses 为空 —— 查到了运单，但暂时没有任何节点。
• success: false 且带 error.code —— 请求本身有问题，或对方明确返回「无此单」。

看清这一点，再对号入座去下面的情况里找原因。

二、情况一：刚发货，轨迹还没上网

最常见、也最不用担心的一种。包裹揽收后，物流信息通常要几个小时到一天 才会同步到查询系统。这段时间查，往往是 success: true 但轨迹为空， 或者返回 NOT_FOUND。对应处理：等一等再查，别几分钟就重试一次。 面向消费者时，直接提示「物流信息尚未更新，请稍后再查」即可。

三、情况二：运单号或快递公司选错

运单号打错一位、或者选错了快递公司，都会让查询落空。接口会用两个错误码区分：

特别提醒：本接口不会自动识别快递公司，courierCode 必须由你明确指定。 把顺丰的单号配上中通的编码，要么报错、要么查出别人的轨迹。选对公司是查得到的前提。

四、情况三：NOT_FOUND —— 查到了但暂无信息

NOT_FOUND 的意思不是「接口坏了」，而是查询动作成功执行、但对方没有这条运单的信息。 它可能是情况一（刚发货没上网）的表现，也可能是单号确实不存在。这里有个容易踩的坑：

NOT_FOUND 是会计费的（billable: true）—— 因为接口确实去查了。 所以千万别写成「查不到就每隔几秒重试」的死循环，那会白白烧掉额度。 正确做法是隔一段时间（如 30 分钟）再查，并设一个最大重试次数。

五、情况四：该快递公司还在准备中

如果某家快递公司的查询功能尚未上线，接口会返回 COURIER_PREPARING， 并且不计费（billable: false）。这不是错误、也不用重试， 当作「该公司暂不支持」处理即可，等功能上线后自然能查。哪些公司已可查、哪些开发中， 可实时调 GET /v1/tracking/couriers 获取。

六、情况五：参数没填全

少传了 courierCode 或 trackingNumber，接口返回 MISSING_PARAMS。 这是纯粹的请求体问题，补齐字段再发即可，同样不计费。

七、用一段代码把原因分开

开发者视角，把上面几种情况在代码里各自分流，逻辑就清晰了：

function paicha(r) {
  // 查到了但暂无轨迹：多半是刚发货，稍后再查
  if (r.success && r.data.progresses.length === 0) {
    return '物流信息尚未更新，请稍后再查';
  }
  if (r.success) return '正常';

  switch (r.error.code) {
    case 'INVALID_TRACKING_NUMBER':
    case 'MISSING_PARAMS':
      return '单号或参数有误，请检查后重填';   // 不重试
    case 'UNSUPPORTED_COURIER':
      return '快递公司编码不正确';
    case 'COURIER_PREPARING':
      return '该快递公司暂不支持（不计费）';
    case 'NOT_FOUND':
      return '暂无该单信息，30 分钟后再查（已计费，勿高频重试）';
    case 'TRACKING_FAILED':
      return '查询一时出错，请指数退避后重试';
    default:
      return '未知情况';
  }
}

八、给普通用户的一句话建议

如果你不是开发者，只是查自己的包裹查不到，记住三点就够： 刚发货请隔几小时再查；确认单号一位没错； 确认选对了快递公司。绝大多数「查不到」都属于这三种，通常等等就有了。

九、小结

• 先分清是「查到了但没轨迹」还是「报错」，两者处理完全不同。
• NOT_FOUND 会计费，别高频重试；COURIER_PREPARING 不计费，无需重试。
• 格式 / 参数类错误改对再发；TRACKING_FAILED 才用退避重试。

各错误码的计费与重试策略详见快递批量查询与错误处理； 运单号格式怎么核对见快递单号格式大全； 字段与错误码完整列表见接口文档。 想马上验证一个单号，用首页在线演示即可。