Quotas and 429 responses

Each Application has a Quota: how many requests per second each of its API Keys can send, and how large a burst it can send at once.

How the Quota works

• requests_per_second is the sustained rate. The gateway gives that many tokens back every second.
• burst is the most requests a key can send at once, after a quiet period. Each request uses one token.
• The Quota applies to each API Key of the Application. A new Application starts with a low default Quota, meant for evaluation. The Application page shows its current Quota.

When you send too many requests

When a key has no token left, the gateway answers 429 with the error rate_limited, and a Retry-After header that gives the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{"error":"rate_limited","message":"The API key quota is exhausted. Retry in 2 s.","request_id":"3f0c9a52-6d1e-4c41-9a57-0b8e2f1d7c44"}

Wait at least Retry-After seconds before you try again, and spread your requests rather than sending them all at once. A retry sent sooner gets another 429.

The Usage tab of the Application shows how many 429 responses you received and, next to the Quota, the busiest minute and the API Key that sent it.

Ask for a higher Quota

FIVB raises a Quota on request. Use the contact link on your Application page, and tell FIVB:

• the Application ID (app_…) and what the Application does;
• the rate you need, and when you need it;
• your current usage, as the Usage tab shows it.

A new Quota applies within seconds of the change, without new keys.

See also Application and Key limits.