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) - Read more below

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:

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

Rate Limit
(Response Units/Secod)

Burst
(Peak Response Units/Second)

Abritrum

15

25

Acala

50

100

Astar

100

100

Polkadot

200

200

Kusama

200

200

Westend

200

200

Statemint

200

200

Statemine

200

200

Collectives

200

200

DFK Chain

15

25

Moonbeam

50

100

Moonriver

50

100

Moonbase Alpha

50

100

Magnata X

50

50

BNB Smart Chain

15

25

Clover

2

10

Composable Finance

2

10

Ethereum

15

25

Edgeware

2

10

Efinity

2

10

Evmos

15

25

Fantom

15

25

Fuse Network

15

25

Gnosis

15

25

Goerli

15

25

Harmony

15

25

HydraDX

2

10

Optimism

15

25

Osmosis

15

25

Parallel Finance

2

10

Parallel Heiko

2

10

Polygon

15

25

Quartz

2

10

Unique Network

2

10

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