> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/faria-suite/integrating-with-faria-suite-apis/rate-limitations-and-throttling.md).

# 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.