Rate Limit Exceed

When a single user makes too many requests to Horizon in a one hour time frame, Horizon returns a rate_limit_exceeded error. By default, Horizon allows 3600 requests per hour – an average of one request per second.
If you are encountering this error, please reduce your request speed. Here are some strategies for doing so:

  • For collection endpoints, try specifying larger page sizes.
  • Try streaming responses to watch for new data instead of pulling data every time.
  • Cache immutable data, such as transaction details, locally

Attributes

As with all errors Horizon returns, rate_limit_exceeded follows the Problem Details for HTTP APIs draft specification guide and thus has the following attributes:

Description Type Attribute
The identifier for the error. This is a URL that can be visited in the browser URL Type
A short title describing the error String Title
An HTTP status code that maps to the error Number Status
A more detailed description of the error String Detail
A token that uniquely identifies this request. Allows server administrators to correlate a client report with server log files String Instance

Rate Limiting

In order to provide service stability, Horizon limits the number of requests a client can perform within a one hour window. By default this is set to 3600 requests per hour—an average of one request per second. Also, while streaming every update of the stream (what happens every time there’s a new ledger) is counted. Ex. if there were 12 new ledgers in a minute, 12 requests will be subtracted from the limit.
Horizon is using GCRA algorithm.


Response headers for rate limiting

Every response from Horizon sets advisory headers to inform clients of their standing with rate limiting system:

Description Header
The maximum number of requests that the current client can make in one hour X-RateLimit-Limit
The number of remaining requests for the current window X-RateLimit-Remaining
Seconds until a new window starts X-RateLimit-Reset

In addition, a Retry-After header will be set when the current client is being throttled.