配额和速率限制指南

FedEx 每天都会收到成千上万的 API 请求。面对如此庞大的请求容量，我们使用了三种节流机制进行管理。我们制定了配额、速率限制和阈值，高速高效地实现 FedEx 资源分配。

配额根据每个组织和每个 API 项目进行定义。

 

每个组织的配额

交易配额是指一个组织在一天内允许的最大 API 请求数量。这意味着 API 消费者应考虑为一个组织内所有项目发起的 API 请求总数。无论 FedEx API 响应中返回的数据量如何，每个请求的计数均相同。

示例：一个组织每天有 500,000 个 API 请求的配额。如果一个组织在一天的前几个小时内提交 500,000 个请求，就会达到配额上限。在当天剩下的时间里，将对每个请求返回错误代码“429 – Too many requests（太多请求） – 超出每日交易配额。格林威治标准时间 12:00AM 之后重试”，直到第二天

 

每个 API 项目的配额

此配额应用于两个不同层面：项目和功能。

我们所说的功能指的是什么？

每个 API 按所属功能分组。每个功能组都是一个或多个端点的集合。例如，追踪 API 功能具有 6 个 API 端点，而地址验证功能只有 1 个 API 端点。

追踪功能的默认“每个项目每个功能 (PCPP) 配额限制”是每天 10 万个请求。也就是说，如果从组织内任何一个项目到追踪功能中 6 个端点之一的流量超过此限制，我们就会在当天结束前一直向您发送错误“429 'Too many requests'（太多请求）”。这适用于 6 个端点的所有后续追踪请求

示例：如果一个项目的每个追踪功能均有 10 万个请求限制（共 6 个端点），则所有 6 个端点的交易总数将会计入这 10 万个请求限制中。如果您的项目超过该限制，对于后续追踪交易，您将在当天格林威治标准时间凌晨 12:00 后收到“429 – Too many requests（太多请求） – 超出每日交易配额”的错误代码。

 

速率限制

每个项目每 10 秒的交易速率限制为 1,400 笔交易。如果交易在每个 10 秒的时间范围内超过这个限制，就会实施节流限制。

如果在前几秒内达到此限制，则在 10 秒窗口的剩余秒内发送的任何交易都将被节流。在此节流期间，将返回一个错误代码，内容为“429 – Too many requests（太多请求）”。

如果 FedEx 在前 2 秒内收到 1,400 个请求，则任何后续交易都将在接下来的 8 秒内受到节流，并会返回错误消息“429 – Too many requests（太多请求） – 我们短期内收到太多请求。请稍候再试”

10 秒过后，节流限制将被解除，另一个计数器将开始追踪接下来 10 秒的请求数量。

 

阈值

阈值应用于 IP 地址层面，使 FedEx API 授权流程具有弹性。此机制仅适用于 Auth token 生成服务。阈值有两种：

  1. 突发阈值：在 5 秒的时间内，每秒连续点击 3 次
  2. 平均阈值：在 2 分钟的时间内，每秒连续点击 1 次
  • 一旦公共 IP 地址违反任何这些阈值限制，它将受到 10 分钟的处罚，并且在这 10 分钟时间范围内的所有进一步请求都将收到“403 Forbidden（禁止）”状态代码
  • 如果 API 消费者在此处罚时间内继续违反任何阈值限制，则处罚时间将被延长。API 用户可以通过在接下来的 10 分钟内不违反阈值限制来结束他们的处罚时间
  • 阈值机制基于用户的公共 IP 地址。如果用户在一个公共 IP 后面设置 10 个虚拟机实例，则来自该 IP 地址的所有请求都将计入阈值限制

 

流量管理

这三种机制分别针对流量管理的一个不同方面：

  • 配额应用于组织层面：一个组织内所有 API 产生的组合流量将受此交易配额的约束。

  • 配额应用于项目层面：一个项目内针对一个 API 功能产生的组合流量受此交易配额的约束。

  • 速率限制应用于项目层面：一个项目内所有 API 产生的组合流量将受此速率限制的约束。

  • 阈值应用于 IP 地址层面。

注：FedEx 可能会降低上述任何节流机制的限制，以防止误用、过度使用和滥用。FedEx 保留在不事先通知的情况下更改分配的权利，从而保持 API 消费者之间的公平访问并有效和高效地分配 FedEx 资源。

常见问题解答

是否所有来自不同项目的组织的 API 交易都计入配额？
配额应用于组织层面。在一个组织下，可以有一个或多个项目，在每个项目下，可以有一个或多个 API。因此，来自不同项目的所有 API 产生的组合流量（属于同一组织）都计入每日配额。

如果配额违规和速率限制违规都返回相同的 429 错误，如何确定我发生了哪种违规？
您可以通过阅读错误消息来确定违规情况。

 

违规 错误消息
每个组织的配额 Too many requests（太多请求）：超出每日交易配额。格林威治标准时间凌晨 12:00 后重试
每个 API 项目的配额 Too many requests（太多请求）：超出每个项目的每日配额。格林威治标准时间凌晨 12:00 后重试
速率限制 Too many requests（太多请求）：超出速率限制阈值。10 秒后重试
   

阈值限制违规的解决方案是什么？
OAuth token 的有效期为一小时。我们建议 API 消费者在整个小时内使用此 token，然后仅在前一个 token 过期时才请求新 token。

超过阈值限制的示例是什么？
5 秒和 2 分钟均为观察窗口，分别是突发阈值和平均阈值。在两个窗口的任一窗口期间，如果某个 IP 地址违反了任何一个阈值限制，则会施加阈值惩罚。

示例：如果一个 IP 地址在 2 秒内每秒有 3 次点击，但随后点击率下降到每秒 3 次点击以下，则没有违反突发阈值。然而，如果一个 IP 地址在 5 秒内每秒连续有 3 次点击，随后在 5 秒内有 15 次点击，则已经违反 5 秒内 14 次点击的突发阈值。