Public Rate Limits

OnFinality adds rate limiting to its public API endpoints. By default, the rate limit allows:

HTTP: 3000 response units/minute per IP address

Websocket: 150 response units/second per IP address

We have different rate limits set for private API endpoints (e.g. ones with API tokens attached) - See more here https://onfinality.io/pricing

How do we measure this?

For web sockets, we use the Token Bucket approach. Each web socket connection has a “bucket” of tokens, representing allowed web socket responses.

For our standard rate limit of 150 response units per second:

• 150 tokens are added to the bucket per second

• The bucket can hold a maximum of 150 tokens. If a token arrives at the bucket when it is full it will be discarded

That means that each web socket connection can sustain a steady stream of 150 response units per second.

Other networks, such as Moonbeam, have a higher burst setting than the per second limit. For example, in a setup of 50 response units per second with 100 burst:

• A new connection opens with 100 tokens in their bucket

• 50 tokens are added to the bucket per second

• The bucket can hold a maximum of 100 tokens. If a token arrives at the bucket when it is full it will be discarded

That means that each Moonbeam web socket connection can sustain a steady stream of 50 response units per second, and short bursts of 100 requests.

Read more on Wikipedia: https://en.wikipedia.org/wiki/Token_bucket

Rate Limit Responses

When a web sockets connection receives a response but has no available tokens OnFinality will return the following error:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Content: {"message":"API rate limit exceeded"}
Retry-After: 1
X-RateLimit-Limit-Minute: 900
X-RateLimit-Remaining-Minute: 0
RateLimit-Limit: 900
RateLimit-Remaining: 0
RateLimit-Reset: 1

We recommend pausing requests over the web sockets connection for several seconds after receiving one of the above error messages to allow the token bucket to fill before trying again.

Access Higher Rate Limits

Rate limits only apply to the Public API and endpoints that have a free API key.

If an app requires a higher rate limit they can upgrade to a paid plan for their OnFinality Workspace and attach their API key to their request. Upgrade now at https://app.onfinality.io

Public Rate Limit Exceptions

The following public API endpoints have rate limits different to the default. These may change at any moment and without warning.

Technical Solution

For networks who would like to replicate the rate limit on their own public API endpoint

https://pkg.go.dev/golang.org/x/time/rate

https://en.wikipedia.org/wiki/Token_bucket