Rate Limitations and Throttling

Problem Statement

The public API for our Faria range of products is a shared resource designed to be highly available as a general-purpose tool for integrations and other solutions. While we encourage clients to enrich their data needs with use of ManageBac+ and OpenApply's Public APIs, we also need to balance that value while also protecting shared resources. Rate limiting (throttling) is a standard practice used to safeguard API resources, and involves the following methods:

• Enforcing a rate limit with 429 responses

• Changing rate limits at any time to optimize system resources

• Configuring different rate limits on different endpoints

• Changing the number of records that are returned, for endpoints that return a collection of records.

• Maintaining different rate limits per region

We therefore ask the following of our client applications:

• Client applications are asked to expect 429 response codes, and gracefully handle them

• Client applications are asked to configure recurring processes conservatively, i.e. to only fetch data once per day

• Client applications are asked to manage the number of requests being made, especially for mission-critical applications

Rate Limiting

The rate limits may be adjusted at any time without prior notice to maintain reliability.

• An 429 HTTP response indicates that the rate limit has been exceeded. This is an intentional behavior, signaling to the application it needs to wait before trying again

• Clients can use the response headers of a 429 response, in particular the X-RateLimit-Reset response header, to determine the exact time (in UTC) that a subsequent re-try will succeed (assuming no further requests are made)

429 Response Headers

When a 429 response is returned, clients may use the headers to re-try. The current rate limit can be calculated via X-RateLimit-Limit divided by X-RateLimit-Period. The below example shows the values for a rate limit of 50 requests per second (per IP):

Header Name	Description	Example
X-RateLimit-Limit	The number of requests that can be sent in the period indicated by X-RateLimit-Period	50
X-RateLimit-Period	The denominator of the rate limit, in seconds	1
X-RateLimit-Reset	The time when a request can be re-tried.	2021-10-28 01:29:40 UTC

Best Practices

To ensure high availability and minimize throttling, schools should consider the following strategies.

Schedule API Calls Efficiently:

• Most use cases can be satisfied with overnight processes.

• If more frequent updates are required, hourly refreshes should suffice.

• Avoid setting up recurring processes that fetch thousands of records unnecessarily.

Use Polling for Efficient Data Retrieval:

• Instead of fetching all records, use the modified_since (MB) or since_date (OA) parameter to request only updated records since the last query.

• This approach improves performance and reduces server load.

• Not all endpoints support polling. Refer to the API documentation to check if the endpoint includes a filter for updated records.