When the Toast-Restaurant-External-ID header is included in the request, then rate limiting is applied per restaurant location.

If the Toast-Restaurant-External-ID header is absent, then rate limiting is applied per IP address. For example, the partners API does not require a restaurant context, and you do not provide restaurant context for requests for an authorization token.

When rate limits are applied per restaurant location, requests that your API client makes for one restaurant location do not affect the client's rate limits for any other restaurant. In other words, if Client A has reached its rate limit for Restaurant A, it can continue to make requests for Restaurant B until it exhausts its rate limit for Restaurant B.

A rate limit is a collection of limits. For example, 20 requests per second and 10,000 requests per fifteen minutes.

Toast APIs return header fields in response to each request that report on the specific limit within a rate limit that is the closest to being exceeded.

For more information, see Rate limiting header fields.

Toast APIs use fixed time slices when they calculate whether the individual limits within a rate limit were reached.

In this approach, each individual limit is associated with a time slice that has a fixed start and end time. For example, you are limited to 20 requests in the 09:00:00 to 09:00:01 time slice, and 10,000 requests in the 09:00:00 to 09:15:00 time slice.

The Toast APIs track the requests made within each time slice independently. When a time slice ends, the limits associated with that time slice are reset.

To illustrate this concept, consider the following example:

With each response, the Toast APIs return a header field that tells you when the time slice for the limit that is closest to being exceeded will be reset.

For more information, see Rate limiting header fields.

Toast APIs use the following rate limit types:

The global rate limit has the highest priority, followed by the API rate limit, and then the endpoint rate limit.

When a rate limit with a higher priority is reached, the client application is considered rate limited, even if rate limits with a lower priority have not been reached yet.

To better understand how rate limit priority works, consider the following example:

At 09:00:00, ClientA makes a request to the orders API service for RestaurantA. After this request is made, the requests remaining on each rate limit are:

Between 09:00:00 and 09:00:01, ClientA makes an additional 19 requests for RestaurantA to services other than the orders API. After these requests are made, the requests remaining on each rate limit are:

Because the global rate limit has the highest priority and its rate limit has been reached, the client application is rate limited, even though orders API requests are still available. ClientA can no longer make requests until the next time slice starts at 09:00:01.

The following header fields are returned for every request to inform you of the rate limit that you are closest to exceeding. They are:

When a rate limit is exceeded, an additional header, Retry-After, is provided in the 429 HTTP response to help you to recover from the rate limited state. This header gives you the number of seconds until the request count is reset for the rate limit specified in X-Toast-RateLimit-By.

The header fields are in the context of the request. For example, consider a GET request to the /orders/{guid} endpoint:

The values in these header fields may change significantly as you make API requests. They reflect the rate limit type and the individual limit within that rate limit type that is closest to being exceeded. These values change as requests are made.

Toast APIs return a 429 HTTP response code when an API client that has been rate limited submits a request.

If your client receives a 429 response, it should stop making requests and inspect the X-Toast-RateLimit-Reset or Retry-After header field to determine when it can start making requests again.

To understand how account rate limits work, consider the following example:

With the standard rate limits that apply to all API accounts, it would be possible for Account A's integration to send 200,000 requests to the orders API in a single second (20 requests per second X 10,000 locations), potentially overwhelming the service.

To avoid this situation, Toast support assigns Account A an account rate limit of 20,000 requests per second for the orders API. This means that:

Account rate limits are applied per API or per endpoint. Requests that your integration client sends to one API or endpoint do not affect the client's rate limits for other APIs or endpoints. In other words, if Client A has reached its account rate limit for an API during a given time slice, it can still make requests to other Toast APIs during the same time slice. This also holds true for endpoint requests. If Client A has reached its account rate limit for an endpoint during a given time slice, it can still make requests to other endpoints.

The value ACCOUNT is added to the X-Toast-RateLimit-By header field when an account rate limit is the closest to being exceeded:

If you are an integration provider with an account rate limit, and additional restaurant locations add your integration to their restaurant, those additional locations will contribute to the total number of requests your integration makes across all locations. This can potentially cause the integration to exceed the account rate limit. For this reason, as additional locations add your integration to their restaurant, you may need to adjust how your integration handles throttling to ensure it doesn't exceed its account rate limit.