Quotas & rate limits guide

FedEx APIs are subject to three throttling mechanisms: quotas, rate-limits, and thresholds.

Quotas

The transaction quota is the maximum number of API requests that can be submitted by an organization within a day. This means that API consumers should consider the total number of API requests initiated for all projects within their organization. Each request counts equally, regardless of the volume of data returned in the FedEx API response.

Example: An organization has a quota of 500,000 API requests per day. Within the first few hours of the day, this organization has submitted 500,000 requests and so reached their daily quota. For the rest of the day, an error code of “429 – Too many requests – Daily transaction quota exceeded. Retry after 12:00AM GMT,” will be returned for each request until the next day.

Rate limits

Each project has a transaction rate limit of 1400 transactions in the span of 10 seconds. Throttling restrictions are applied if transactions exceed this limit during each 10-second timeframe.

If this limit is reached in the first few seconds, then any transactions sent in the remaining seconds of that 10 second window will be throttled. During this throttling period, an error code that reads “429 – Too many requests” will be returned.

If FedEx receives 1400 requests in the first 2 seconds, then any subsequent transactions will be throttled during the next 8 seconds and an error message that reads “429 – Too many requests – We have received too many requests in a short duration. Please wait a while to try again,” will be returned.

After 10 seconds elapses, throttling restrictions will be lifted and another counter will start to track the number of requests over the next 10 seconds..

Thresholds

Thresholds are applied at the IP address level in order to make the FedEx API authorization process resilient. This mechanism is only applicable to the OAuth token generation service. There are two types of thresholds:

1. Burst threshold: 3 hits per second, continuously, during a span of 5 seconds
2. Average threshold: 1 hit per second, continuously, during a span of 2 minutes

Once a public IP address violates any of these threshold limits, it will then be penalized for 10 minutes, and all further requests during this 10-minute timeframe will receive a “403 Forbidden” status code.

If API consumers continue to violate any threshold limits during this penalty time, the penalty time will be extended. API users can end their penalty time by not violating the threshold limit for the next 10 minutes.

Threshold mechanisms are based on a user’s public IP address. If a user sets up 10 virtual machine instances behind one public IP, then all requests from that IP address will count toward the threshold limit.

Traffic management

Each of these three mechanisms addresses a distinct aspect of traffic management:

• Quotas are applied at the organization level, i.e. the combined traffic generated by all APIs within an organization will be subject to this transaction quota.

• Rate limits are applied at the project level, i.e. the combined traffic generated by all APIs within a project will be subject to this rate limit.

• Thresholds are applied at the IP address level.

Note: FedEx may mark down limit(s) of any of the above mentioned throttling mechanisms to prevent misuse, overuse, and abuse. FedEx reserves the right to change allocation without prior notice in order to maintain equitable access among API consumers and to allocate FedEx resources effectively and efficiently.

FAQs

Are all of an organization’s API transactions from different projects counted towards the quota?
Quota is applied at the organizational level. Under one organization, you can have one or more project(s), and under each project, you can have one or more APIs. As a result, the combined traffic generated by all APIs from different projects — all under the same organization — is counted towards a daily quota.

If the same 429 error is returned for both a quota violation and a rate-limit violation, how can I identify what sort of a violation I’ve incurred?
You can identify the violation by reading the error message.

What is the solution for a threshold limit violation?
An OAuth token is valid for an hour. We suggest that API consumers use this token for that full hour then request a new token only as the previous one expires.

What is an example of when the threshold limit is crossed?
Both 5 seconds and 2 minutes are observation windows, for the burst threshold and average threshold, respectively. During either of these windows, if either of the threshold limits is violated from an IP address, then the threshold penalty is imposed.

Example: If an IP address has 3 hits per second for 2 seconds, but then the hit rate drops below 3 hits per second, the burst threshold has not been violated. However, if an IP address has 3 hits per second continuously for 5 seconds (e.g. at least 15 hits in 5 seconds with this hit rate maintained), then the burst threshold has been violated.