Rate Limit

Throttling

One way of ensuring security of our GraphQL API is by applying throttling. With API throttling we limit the number of user requests within a certain period of time to make sure the API doesn't get disabled by e. g. denial of service attacks.

To be able to determine what an acceptable amount of requests within a certain period of time is, the operation complexity analyzer tool is utilized. In shorts terms this tool calculates the complexity of a request and compares it to the specified permitted operation complexity.

To read more about how the operation complexity is calculated click here.

Secondary throttling

In addition to the primary throttling based on operation complexity, a secondary throttling mechanism is implemented to limit the total complexity cost incurred by a user within a one-minute window. This measure helps prevent excessive resource consumption over time, even if individual requests fall within acceptable complexity limits.

🚨 Below are only examples; you must investigate the cost of each individual entity yourself in Nitro here. If no cost is specified, the standard applies according to the example.

Cost examples

While queries with a complexity cost exceeding max limit are automatically rejected, there are cases where datasets are too large to process effectively, even if the complexity cost is below this threshold. This limitation is particularly relevant because the API does not currently support sub-paging, meaning all requested (underlying) data must be delivered in a single response. Your limit is exposed in the extension of each response-body.

The following is an example of a query which exceeds the permitted operation complexity. In this query we want to retrieve the first 5000 errand rows with some related information (default number of rows in a single retrieval is 50, while 5000 is the max number of rows).

The query complexity is calcutaled accordingly:
(Primary field × number of rows) + ((number of joins + number of columns) × number of rows) = complexity (cost)

Example:
(5 × 5000) + ((2 + 19) × 5000) = 130000 complexity (cost)