# API rate limits

The GraphQL API's limits are based on a calculated cost for each query. Every request is subject to throttling under our general limits.

All requests that are made after the limit has been exceeded are throttled and an {errors: [{ message: "Throttled" }]} error is returned. Requests succeed again after enough space has accumulated in the bucket. Limits are calculated using the leaky bucket algorithm. You can use the GraphQL response to see the status of the throttle.

# General API rate limits

The leaky bucket rate limits function like the REST API's rate limiting system, but consider the cost of requests over time, rather than the number of requests. An app is given a bucket of 1000 cost points, with a leak rate of 50 cost points per second. This means that the total cost of your queries cannot exceed 1000 points at any given time, and that room is created in the app's bucket at a rate of 50 points per second. By making simpler, low-cost queries, you can make more queries over time.

The limit uses a combination of the requested and the actual query cost. Before execution begins, the app’s bucket must have enough room for the requested cost of the query. When execution is complete, the bucket is refunded the difference between the requested cost and the actual cost of the query.

# Cost calculation

Every field in the schema has an integer cost value assigned to it. The cost of a query is the sum of the costs of each field.


Connection fields have a multiplying effect on the cost of their sub-selections based on the first or last arguments.

# Requested and actual cost

Orderchamp calculates the cost of a query both before and after query execution. The requested cost is based on the number of fields requested. The actual cost is based on the results returned, since the query can end early due to an object type field returning null, or connection fields can return fewer edges than requested.

# Single query limit

A single query to the GraphQL API cannot exceed a cost of 1000. This limit is enforced before a query is executed based on the query's requested cost.

# Recommendations to avoid throttling errors

Design your app with API rate limits in mind to best handle request limits and avoid errors. To avoid rate limiting:

  • Vary time intervals of requests to avoid sending traffic in spikes.
  • Avoid requesting overlapping data.
  • Use the query response to balance your requests.

# GraphQL response

The response includes information about the cost of the request and the state of the throttle. This data is returned under the extensions key:

"extensions": {
  "throttle": {
    "requestedCost": 0,
    "actualCost": 0,
    "limit": 1000,
    "remaining": 0,
    "restoreRate": 50