API Request Rules
- esnata (Unlicensed)
- Ilya Titaev
Limits on the number of requests
There are limits on the number of API requests per hour for all client applications. If the limit on the number of requests is exceeded, the request will return a response with the code 429 Too Many Requests and the rate_limit_exceeded status, the next request can be made only in the next hour. The limit is general and applies to all client applications. Information about the limit on the number of requests of this type, the number of remaining requests until the limit is exhausted, and the time until the request counter is reset is transmitted in the special headers of each REST API response.
Header | Description |
|---|---|
X-RateLimit-Limit | Limit on the number of requests per hour for this resource |
X-RateLimit-Remaining | The number of remaining requests before the limit is reached |
X-RateLimit-Reset | Number of seconds before resetting the request counter |
There are also limits for the /oauth and /login resources:
20 requests per second
6 simultaneous connections
An example of the distribution of the limit on the number of requests by client applications
The client has 4 applications. 2 clients and 2 extensions.
1 application of the "client" type has a limit of 100
2 application of the "client" type has a limit of 1000
3 application of the "extension" type has a limit of 1000
4 application of the "extension" type has a limit of 1000
1 application generated 55 requests in the current hour
2 application generated 5 requests in the current hour
3 application generated 35 requests in the current hour
4 application generated 5 requests in the current hour
Total number of requests for 4 applications = 100
at the next request, application 1 will receive 429 Too Many Requests and the rate_limit_exceeded status, since the total request counter is 100, which is the limit for application 1.
The rest of the applications will not receive Too Many Requests until the total counter of the client application reaches 1000
If a Personal Application Limit is set, then the application increments its counter and the total counter for all applications, but is blocked only if its personal requests have reached the personal limit.
Return codes and statuses
This section contains the codes and statuses that the API server returns, as well as a description of their values.
Successful request codes
Request method | Success code |
|---|---|
GET | 200 |
POST | 201 |
PUT | 200 |
DELETE | 204 |
Request error codes and statuses
If the request fails, the response returns a message with the code 4XX. Additionally, the response may contain the status field, which contains a value that can be used to distinguish errors with the same code.
Code | Status | Description |
|---|---|---|
401 |
| The user is not logged in. The access token is not passed in the request, or the access token is expired or invalid (see Creating and authorizing applications). |
401 | invalid_grant | The evaluation of the token can be evaluated via refresh_token. If necessary, re-authorization |
403 | access_denied | This user does not have the right to access the requested resource |
403 | user_blocked | This user or the client to which the user belongs is blocked |
403 | user_access_type_deny | Insufficient user access level |
403 | app_access_type_deny | The application's access level is not sufficient for this resource (see Creating and authorizing applications). |
404 |
| The resource does not exist |
404 | client_not_found | The client with the ID passed in the path was not found |
404 | extension_not_found | Internal number with the ID passed in the path was not found |
405 |
| The resource does not support this request method |
413 |
| The request body size is larger than the allowed size (10 MB) |
413 | large_file | The size of the uploaded file is larger than the allowed size for this resource |
429 | rate_limit_exceeded | Exceeded the limit on the number of API requests (see Limits on the number of requests) |
400 | limit_exceeded | Exceeded the limit on the number of resources of the created type (see Client limits) |
400 | input_error | Invalid form of one of the arguments passed in the request body, or the absence of one of the required arguments |
400 | wrong_extension_type | Attempt to use a resource that does not belong to this internal number type |
400 | wrong_file | Invalid format of the uploaded file |
400 | unresolvable_me | The @me resource ID cannot be applied to this user and resource. |
400 | no_records | There are no records in the requested date range to create an archive of conversation records |
400 | records_size_too_large | The size of the records in the requested date range is greater than the maximum allowed for creating an archive. You should choose a smaller date range |
400 | archive_already_requested | An archive of conversation records for this client has already been requested. The archive can be requested again only after the previous archive has been downloaded |
400 | email_duplicate | The e-mail address passed as a parameter has already been used |
400 | already_exists | The resource that is being created already exists |
5xx |
| Server-side errors. The administrator must be informed in order to take appropriate action |
You don't need to make more than one request per action. If an error was received during the previous attempt to make a request, it means that you need to take some actions and only then repeat the request. Re-sending the request should be initiated only by the user (when the request is initiated by the user) or after a certain time (for automatic requests), but in no case in an infinite loop. The user should find out about the error in the corresponding notification.