Rate Limitations and Throttling – SchoolsTechnology Help Centre

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.

A 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

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.