Context
APIs (Application Programming Interfaces) allow third-party applications to access data and services in a standardized way. To ensure security, availability, and quality of service, it is essential to implement two mechanisms:
Authentication of API calls
Rate limiting of the number of requests
Our APIs are available to any authenticated user (see documentation) and allow, depending on the level of permissions, direct access to various account-related resources (nodes, agents, configurations, etc.) or the ability to trigger actions.
The concept of rate limiting
Rate limiting consists of restricting the number of requests a client can perform within a given time period. The goal is to ensure service stability and to prevent abuse (overload, denial of service, uncontrolled usage).
Why limit requests?
Protect the infrastructure against excessive load
Ensure a fair distribution of resources among users
Prevent malicious usage (bots, brute-force attacks)
Rate limiting rules
The active limitations mainly concern two identifying factors.
Note: both limiting modes apply simultaneously. Any potential block will result from whichever limit is reached first.
API Key
At the application account level, this key may be shared by multiple users, whose API tokens are derived from it.
Maximum number of requests: 10
Regeneration rate: 10 requests per second
API Token
At the individual user level, this token, linked to a common API key, is personal.
Note: multiple API tokens belonging to the same user (identified by their email address) used in parallel do not extend the limit and are counted as a single source.
Maximum number of requests: 20
Regeneration rate: 1 request per second
Best practices for API consumers
Cache responses to reduce unnecessary requests
Implement a retry mechanism with progressive delays in case of 429 errors
Monitor consumption to remain within the authorized limits
Response Headers
API responses will expose, among the header information, several keys useful for error management:
X-RateLimit-Remaining: number of requests still allowed before being blocked
X-RateLimit-Retry-After: number of seconds before a new request can be sent (0 as long as no block has been triggered)
X-RateLimit-Limit: maximum number of concurrent requests that can be sent
-
X-RateLimit-From: rule responsible for the limitation, among:
api_key / api_token: Main rules detailed in the “Rate limiting rules” section
ip / user_id: Specific limitations related to remote access