常见问题 FAQ

集成 TrackEasy API 时的 10 个最常见问题。点问题跳到答案。

Q1. 返 401 身份验证失败 怎么办？

三个原因，逐个排查：

1. 没传 API Key：检查 request 是否有 X-API-Key header（兼容 17token）
2. Key 拼写错：注意前缀 tk_，后面是 48 位 hex，全小写无空格
3. 账号被禁用 / Key 被重置：调 GET /api/v1/auth/me 看账号状态，若 401 联系管理员重置

curl -H "X-API-Key: tk_your_key_here" \
  https://api.168tracking.com/api/v1/auth/me

Q2. 返 429 超出请求限制 怎么办？

每个 endpoint 有独立限流（详见 API 参考 顶部速率限制表）。

• POST /trackings/create：3 req/s
• POST /trackings/batch：10 req/s
• GET /trackings/get：2 req/s（**最严**）

Q3. 创建时返 4102 物流单号不存在？

4102 一般出现在 查询 场景（GET /trackings/get），意思是「这个单号没在你账号下注册」。

排查步骤：

1. 先调 POST /trackings/create 把单号注册进来
2. 等 5-15 秒（后台异步查询）
3. 再调 GET /trackings/get?tracking_numbers=...

Q4. 注册成功但查不到轨迹？

几种常见原因：

• 单号格式错：从物流商给的原样复制（带空格就去掉）
• 物流商识别错：手动指定 courier_code（如 usps、ups、fedex）
• 新单号还没上网：物流商扫描需要时间，等 1-2 小时后再查（用 retrack 强制重查）
• 物流商不在支持列表：调 GET /couriers/all 看当前支持的物流商

Q5. Webhook 没收到推送？

按以下顺序排查：

1. URL 可达性：调 POST /webhooks/test 看是否 2xx
2. 签名验证失败：检查 X-Webhook-Signature header 的 t=<ts>,v1=<hex>，验签算法 hmac_sha256(secret, ts + "." + body)
3. timestamp drift：客户端时钟偏移超过 5 分钟 → 签名失效。同步 NTP
4. SSRF 拦截：生产环境 URL 不能是 localhost / 私网 IP / 内网域名
5. 投递历史：调 GET /webhooks/deliveries 看最近 50 条投递记录

Q6. 返 4190 额度不足？

当月 quota 已用完。处理方法：

• 免费 plan：每月自动重置（下月 1 号恢复）
• 升级 plan：联系管理员升级到 pro / enterprise
• 查询用量：GET /api/v1/account 看 quota_used / quota_remaining

Q7. 怎么知道一个单号属于哪个物流商？

两种方式：

1. 自动识别（推荐）：不传 courier_code，让后端自动识别（响应里 detected_carrier 字段告知结果）
2. 显式查询：POST /api/v1/carrier/detect 只检测，不创建

Q8. retrack 报错 4113 不允许重新查询？

retrack 强制 1 小时间隔。两次 retrack 之间必须等 1 小时。

建议实现：

• 客户端缓存 last_retrack_at
• UI 倒计时显示「还差 X 分钟可重试」
• 超时后自动允许

Q9. 批量报错 4103 超过 40 个？

单次批量上限 40 个单号。超过会被拒绝（不消耗 quota）。

处理：

• 客户端分片：每 40 个一组，分批调 /trackings/batch
• 或者用 /track/async 一次最多 40 个（异步处理，避免阻塞）
• 千级以上用 /track/batch-stream 流式接收结果

Q10. Webhook 重试会发几次？

最多 14 次，指数回退 2^n × 30s：

失败定义：HTTP 状态码不在 200-299，或超时（10 秒）。客户端必须返回 2xx 才算成功。

还是没解决？

联系开发者支持：

• Email: support@168tracking.com
• Telegram: @trackeasy_support
• 在线客服：168tracking.com 右下角