首页博客指南Tracking API 错误处理：如何管理无效的跟踪号码、速率限制和重试

Tracking API 错误处理：如何管理无效的跟踪号码、速率限制和重试

17TRACK

通过区分无效输入、临时故障、速率限制和货件状态结果来处理跟踪 API 错误。拒绝或更正无效的跟踪号码，而不是在不做任何更改的情况下重试；受到限流时协调请求量；对于临时故障，使用有上限的指数退避和抖动进行重试。在重复注册或其他写入请求之前，先确认第一次尝试是否已成功。

跟踪 API 错误处理：如何管理无效跟踪号码

对于将跟踪数据连接到订单管理系统、仓储平台或面向客户的跟踪页面的开发者而言，目标并不仅仅是减少失败请求，而是在避免重复注册、重试风暴、误导性的配送消息或不必要的支持工单的同时，可靠地展示货件状态。

在选择响应方式之前先对故障进行分类

跟踪集成需要评估多个相互独立的结果：网络请求是否完成、API 是否接受了操作、所请求的每个跟踪项目是否成功，以及货件事件是否可用。将这四项视为单一的成功或失败标志，会造成本可避免的错误。

HTTP 成功响应并不一定意味着批次中的每个项目都成功。反过来，一次成功处理但没有跟踪事件的查询也不一定表示 API 失败。请检查响应正文，并根据提供商记录的说明解释每个结果。

条件建议操作是否原样重试？
号码格式错误或请求字段无效验证并更正输入否
凭证缺失或无效检查凭证、权限和环境更正之前不重试
速率限制响应延迟受影响的工作并降低共享请求压力在要求的等待时间之后，若安全则重试
临时服务故障应用有上限的退避并检查操作安全性通常可以，在重试预算内
提交注册后超时确认注册是否已存在不可盲目重试
查询已接受但没有货件事件遵循记录的跟踪生命周期使用计划刷新，而不是快速重试

HTTP 状态码提供了起点，但不是完整的提供商特定决策树。RFC 9110 定义了 HTTP 语义，而 RFC 6585 定义了 429 Too Many Requests。你的集成还应解释记录的应用错误代码和项目级结果。

无效跟踪号码：区分错误输入与缺失事件

“无效跟踪号码”可能描述不同的问题：标识符格式错误、不支持的承运商和号码组合、缺少必需的承运商字段，或其他提供商特定的验证失败。不要仅仅因为没有返回跟踪事件，就认定号码无效。

在不损坏标识符的情况下进行验证

  • 将跟踪号码存储为字符串。使用数值存储可能会删除前导零或改变较长的标识符。
  • 保留原始输入。保留一个单独的规范化值，以便转换过程可审计。
  • 谨慎进行规范化。在适当情况下删除首尾空格，但只有在记录的规则允许时，才删除内部字符或更改字母大小写。
  • 在本地检查必填字段。在发送请求之前捕获空号码、缺少承运商标识符和无效的请求结构。
  • 避免使用通用的跟踪号码正则表达式。为一家承运商设计的规则可能会拒绝另一家承运商的有效标识符。
  • 确认字段中包含的内容。订单号、仓库参考号和承运商跟踪号码并不可以互换，除非端点明确支持它们。

如果 API 明确拒绝了输入，应将其转入更正流程，而不是自动重试循环。请提供有用的原因，例如“需要承运商标识符”，而不要将所有验证问题都简化为“跟踪失败”。

将“无事件”视为独立状态

货件可能在有跟踪标识符之后，才会出现有用的运输事件。正确的响应取决于 API 记录的状态模型和货件上下文。检查标识符是否来自运输系统、承运商选择是否正确，以及响应是否表示数据待处理，而不是输入被拒绝。

使用不同的内部状态，例如 input_rejected、awaiting_events 和 temporarily_unavailable。这些是建议的应用状态，并非标准化的 API 值。它们有助于防止临时数据缺口变成不准确的客户消息。

在整个集成范围内管理速率限制，而不是按工作进程管理

RFC 6585 将 HTTP 429 定义为速率限制响应，并允许其包含 Retry-After 标头。该标准没有规定通用的跟踪 API 配额或计数方式。限制可能按账户、凭证、端点或其他范围记录；请使用提供商的实际规则。

RFC 9110 为 Retry-After 规定了两种形式：非负秒数或 HTTP 日期。请解析这两种形式。如果该值是日期，请谨慎计算剩余等待时间，并考虑时钟差异。如果缺失或无法使用，请应用已配置的备用退避策略。

当其他工作进程仍在使用同一配额时，仅让一个工作进程独立休眠是不够的。应在相关凭证或账户的共享边界实施速率控制。中央调度程序、共享令牌桶或等效的分布式控制机制可以协调此类流量。

  1. 确定受影响的范围。确定限制适用于哪个端点、凭证或账户。
  2. 遵守服务器的等待指令。如果有效的 Retry-After 值规定了等待时间，不要安排早于该时间的重试。
  3. 延迟受影响的排队工作。当限制确实相互独立时，避免阻塞无关流量。
  4. 降低并发量或请求频率。只等待一次而不改变请求模式，可能会再次造成相同问题。
  5. 保持间隔后恢复。等待结束时，不要同时释放整个积压队列。

在支持的情况下，批处理可以减少请求数量，但必须遵守记录的批次大小和计费规则。不要假设一个批次只消耗一个配额单位。同样，在可用时使用 Webhook 来减少不必要的轮询，同时保留集成所需的对账流程。

使用带退避和抖动的有界重试

当故障可能在不更改请求的情况下自行消除，并且重复操作是安全的，重试才是适当的。临时连接故障和某些服务器错误可能属于此类。格式错误的负载、无效凭证或永久性权限问题通常需要进行更正。

一种实用的备用方案是带完整抖动的封顶指数退避：

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

这里，第一次重试时 retry_index 从零开始；缺失的 Retry-After 不会增加额外的最小等待时间。这些是实现选择，而不是强制性的 HTTP 算法。请根据工作负载和提供商指导选择基础延迟、上限、尝试次数限制和总截止时间。

抖动会将请求分散到一段时间内，而不是让每个工作进程按照相同时间表重复请求。延迟上限限制指数部分；它不应覆盖服务器要求的更长有效等待时间。如果该等待时间超过作业截止时间，应根据策略延迟或终止作业，而不是提前重试。

为每条重试链设置终点

  • 尝试次数限制：限制额外请求的数量。
  • 经过时间限制：停止重试已超过有效处理窗口的工作。
  • 明确的责任归属：选择由哪个层控制重试，以免 HTTP 客户端重试和队列重试意外叠加。
  • 持久化调度：存储延迟作业，而不是依赖短生命周期进程中的长时间休眠。
  • 恢复路径：将耗尽重试次数的作业发送到可审查的失败作业队列，并记录原因和下一步操作。

在持续中断期间，可以考虑使用断路器，暂时暂停常规调用，并允许受控的恢复探测。这是一种应用弹性模式，并不表明任何特定的跟踪提供商都要求使用它。

在重新发送之前解决有歧义的写入操作

超时说明应用程序没有收到完整响应，但并不能证明服务器拒绝或从未处理该请求。在注册跟踪号码或更改跟踪配置时，这一区别非常重要。

RFC 9110 解释了幂等方法，并提醒不要在缺乏依据确认重复操作安全或原始操作未生效的情况下，自动重试非幂等请求。请评估记录的操作语义，而不要假设每个跟踪端点都像只读查询一样运行。

  • 在可用时使用提供商记录的幂等机制，并遵循其范围和保留规则。
  • 对同一逻辑操作的重试使用相同的幂等键；不要假设任意自定义标头都会被接受。
  • 如果支持，在重复有歧义的写入之前检查现有注册。
  • 使用与提供商记录的货件标识一致的本地唯一性约束。
  • 存储操作结果，以便队列重新投递不会自动触发另一次写入。

对于批量操作，请持久化每个项目的结果。仅重试被归类为临时失败的项目，并对结果仍未知的项目进行对账。重放整个批次可能会重复已成功的工作，并不必要地消耗请求配额。

将策略应用于你的跟踪提供商

对于 17TRACK 集成，请将 Tracking API 页面和官方 API 文档作为提供商特定契约的起点。将错误分类器配置化，而不要硬编码通用 HTTP 指南中的假设。

在实施之前，确认相关端点的请求架构、响应封装、项目级错误含义、速率限制范围、批次约束以及重复提交规则。如果使用事件交付，还应确认确认机制、身份验证和重新投递要求。本指南不规定 17TRACK 的具体速率限制数值、重试计划或幂等功能。

将每条已确认的规则记录在从提供商响应到应用操作的映射中：更正输入、修复配置、等待、对账或升级处理。未识别的错误应保留诊断上下文并遵循有界的备用路径，而不是默认进行无限重试。

监控恢复质量并测试故障路径

记录操作、端点、HTTP 状态、应用错误代码、尝试次数、延迟、下一项计划操作，以及提供商在响应中提供的请求标识符。避免记录 API 密钥、不必要的地址信息或不受限制的响应正文。在不需要完整值时，对跟踪标识符进行掩码或哈希处理。

分别跟踪无效输入率、限流、队列年龄、耗尽的重试次数和上次成功同步时间。集成可能具有较低的 HTTP 错误率，但仍提供过时的货件信息。面向客户的页面应保留最近已知的货件状态，并区分刷新失败和承运商报告的配送异常。

在发布之前，测试格式错误的输入、没有事件的有效标识符、Retry-After 的两种形式、缺失标头、部分批次失败、写入后的超时以及队列重新投递。同时模拟持续足够长时间、能够耗尽重试预算的故障。只有当工作可预测地停止或延迟、成功项目不会被不必要地重放，以及失败项目仍可恢复时，测试才算通过。

常见问题

是否应自动重试无效跟踪号码？

如果 API 明确拒绝输入并指出其无效，则不应重试。请先更正号码、承运商选择或必填字段。如果响应实际表示货件事件尚不可用，请使用记录的刷新流程，而不要将其视为验证失败。

HTTP 200 是否意味着批量请求完全成功？

不一定。请检查提供商的响应架构，了解操作级和项目级结果。持久化成功项并隔离失败项，以便重试一个项目时不会不必要地重复其他项目。

跟踪集成应允许多少次重试？

没有通用次数。请根据提供商指导、操作安全性以及结果在多长时间内仍有用，同时设置尝试次数限制和经过时间预算。计划中的后台同步可以承受与交互式客户请求不同的恢复窗口。

是否应在超时后立即将货件标记为失败？

不应。请求超时是集成结果，而不是货件事件。请保留最近已知的跟踪状态，安排安全恢复，并避免将连接问题转换为配送失败通知。

重试耗尽后应如何处理？

将作业移至持久化的失败作业队列或审核队列，并保留其诊断上下文。明确恢复需要更正输入、恢复凭证、提供商协助还是稍后受控重放。不要静默丢弃，也不要重新启动同一个无限重试循环。

来源

Loading