This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Rate limiting header fields

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

X-Toast-RateLimit-By

The type of rate limit that the client application is closest to exceeding: GLOBAL, API, or ENDPOINT.

The other header fields describe a specific limit within this rate limit.

X-Toast-RateLimit-Remaining

The number of requests left in the current time slice for the limit that is closest to being exceeded.

X-Toast-RateLimit-Reset

A timestamp, in UNIX epoch format, for when the next time slice for this limit begins and the request count is reset.

This header field uses the UNIX epoch format because it is easiest to compare programmatically.

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:

  • If the X-Toast-RateLimit-By header field returns GLOBAL, then the rate limit that is closest to being exceeded is the global rate limit.

  • If the X-Toast-RateLimit-By header field returns API, then the rate limit that is closest to being exceeded is the orders API rate limit.

  • If the X-Toast-RateLimit-By header field returns ENDPOINT, then the rate limit for the /orders/{guid} endpoint is closest to being exceeded.

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.