Quotas & rate limits guide

FedEx receives many thousands of API requests each day. We use three throttling mechanisms to manage that large volume. Quotas, rate limits, and thresholds are in place to allocate FedEx resources effectively and efficiently.

Quotas are defined per organization and per API project.

Quotas per organization

The transaction quota is the maximum number of API requests allowed from an organization within a day. This means that API consumers should consider the total number of API requests initiated for all projects within a single 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. If an organization reaches the 500,000 submitted requests within the first few hours of the day, it will have reached its 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

Quotas per API project

This quota is applied at two different levels: project and capability.

What do we mean by capabilities?

Each API is grouped by the capabilities they provide. Each capability group is a bundle of one or more endpoints. For instance, Track API capability has 6 API endpoints while Address Validation capability has only 1 API endpoint.

The default Per Capability Per Project (PCPP) quota limit for the Track capability is 100K requests per day. That means when traffic from any of the projects within an organization to any of the 6 endpoints under Track capability exceeds this limit, then we will send you a "429 'Too many requests'" error until the end of the day. This applies to all subsequent track requests for any of the 6 endpoints

Example: If a project has 100K limit per track capability (with 6 endpoints), the total number of transactions for all 6 endpoints will be counted to the 100K limit. If your project exceeds that limit, then for subsequent track transactions you will receive an error code of “429 – Too many requests – Daily transaction quota exceeded” for the rest of the day 12:00AM GMT.

Rate limits

Each project has a transaction rate limit of 1,400 transactions per 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 1,400 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  – 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 to make the FedEx API authorization process resilient. This mechanism is only applicable to the Auth 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 applied at the organization level: The combined traffic generated by all APIs within an organization will be subject to this transaction quota.

• Quotas applied at the project level:The combined traffic generated for one API capability within a project is subject to this transaction quota.

• Rate limits applied at the project level: 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 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, which are under an 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, followed by a hit rate below 3 hits per second, then the burst threshold has not been violated. However, if an IP address has 3 hits per second continuously for 5 seconds, followed by 15 hits in 5 seconds, then the burst threshold of 14 hits in 5 seconds has been violated.