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

HTTP: 900 requests/minute per IP

Websocket: 50 responses/second per web socket connection, with short bursts of 100 responses.

We have different rate limits set for private API endpoints (e.g. ones with API tokens attached) - Read more below

How do we measure this?

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

  • 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 web socket connection can sustain a steady stream of 50 responses/second, or bursts of 100 responses after saving up tokens over a period.

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:

Protocol

Response Code

Error Message

Example

HTTP

429

API rate limit exceeded

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
CODE

WebSocket

{ "code": -32029, ..}

Too Many Requests, Please apply for an OnFinality API key to receive a higher rate limit

{"jsonrpc":"2.0","error":{"code":-32029,"message":"Too Many Requests, Please apply an OnFinality API key to receive a higher rate limit"},"id":123123}

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 APIs have rate limits different to the default

Public API

Web Sockets Rate Limit

HTTP Rate Limit

Avalanche

5 responses/second

50 requests/minute

Juno

5 responses/second

50 requests/minute

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