Rate limits

How many requests Push accepts per minute, and what to do when you hit a limit.

Push counts requests in a 60-second window. A request with a valid API key counts against the key, its project and the account at once, and the tightest of the three decides. Sending (POST /v1/notifications) and reading (GET /v1/notifications/{id}) both count.

Limits#

Scope	Applies to	Requests per 60 s
Per API key	Every request made with that key	60
Per project	All keys of the project together	300
Per account	All projects of the account together	600
Per IP address	Requests with a missing or invalid API key	120
Per IP address	`GET` and `POST /v1/connect/{token}`	60
Per IP address	`POST /v1/events` and `POST /v1/browsers/{id}/disconnect`	300

NoteA suspended project is refused with 403 PROJECT_SUSPENDED before any limit is counted. Once an IP address sends too many requests with a bad key, it gets 429 RATE_LIMITED instead of 401 UNAUTHORIZED until the window passes.

Over the limit#

Push answers 429 RATE_LIMITED with a Retry-After header: the number of seconds to wait, at least 1. Nothing was sent. Wait that long, then retry with the same Idempotency-Key.

⫻

429 Too Many Requests

HTTP/1.1 429 Too Many RequestsContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11Retry-After: 12
{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down and retry later.",    "requestId": "req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11"  }}

Staying under the limits#

Send one request per notification. A recipient with several browsers is still one request.
Spread bursts out, for example through a queue in your own system, instead of firing them all in the same second.
Poll statuses gently: a few seconds apart, and stop once every attempt is final. See reading statuses.
Use separate projects for separate systems, so one busy system does not use up another's project limit.