Rate Limit

The number of API requests you can make in a time window is limited. For some endpoints such as upload tasks, this limitation becomes more strict.
This limitation prevents malicious activities such as DOS attacks and guarantees the availability of API servers.

These limits may be reduced or increased over time, so to manage your rate limit, use the X-RATELIMIT response headers.
The X-RATELIMIT response headers are returned in each response. These headers specify the status of your rate limit.

If the X-RATELIMIT-REMAINING response header reaches 0, do not send another request and wait until your rate limit is reset, otherwise, you will exceed the rate limit. Use the X-RATELIMIT-RESET response header, which specifies how many seconds you should wait for your rate limit to be reset.
When you exceed the rate limit, you will receive a TOO_MANY_REQUESTS error code with HTTP 429 status. In this case, another response header named RETRY-AFTER is also returned, which specifies how many seconds you must wait before making a new request. The RETRY-AFTER response header has a higher priority than the X-RATELIMIT-RESET response header.

Request

The example code of this section shows the structure of the Rate Limit request. You may see the other request structure keys such as data keys and see how the request is authenticated.

HTTP

cURL

CLI

Python

PHP

POST https://api.vertopal.com/v1/example/endpoint
Authorization: Bearer [APP_TOKEN]

data={
    "app": "[APP_ID]"
}

curl -L -X POST 'https://api.vertopal.com/v1/example/endpoint' \
-H 'Authorization: Bearer [APP_TOKEN]' \
-F 'data={
    "app": "[APP_ID]"
}'

vertopal api -v 1 vertopal/endpoint \
--app "[APP_ID]" \
--token "[APP_TOKEN]" \
-F data='{
    "app": "%app-id%"
}'

from vertopal.api.v1 import API

API.example_method(
    app="[APP_ID]",
    token="[APP_TOKEN]",
)

use Vertopal\API\Credential;
use Vertopal\API\V1;

require "vendor/autoload.php";

$credential = new Credential("[APP_ID]", "[APP_TOKEN]");

V1::exampleMethod($credential);

Response

Header Keys

X-RATELIMIT-LIMIT number<integer>

The maximum number of requests you can send in a time window.

X-RATELIMIT-REMAINING number<integer>

The number of remaining requests you can send in a time window.

X-RATELIMIT-RESET number<integer>

The seconds that your rate limit will be reset. After reset, the X-RATELIMIT-REMAINING value will be equal to the X-RATELIMIT-LIMIT value.
If the RETRY-AFTER response header has been returned, the value of these two response headers will be the same.

RETRY-AFTER number<integer>

The seconds to wait for the TOO_MANY_REQUESTS error to be resolved.

HTTP Status Codes

OK 200

The task has been executed successfully without any errors.

TOO_MANY_REQUESTS 429

Too Many Requests. Retry after [DELAY] seconds.

The example code of this section shows the structure of the Rate Limit response. You may see the other response structure keys such as entity keys.

HTTP

X-RATELIMIT-LIMIT: 10
X-RATELIMIT-REMAINING: 4
X-RATELIMIT-RESET: 6

{
    "result": {
        "output": {
            # sample output data
        },
        "error": {},
        "warning": {}
    }
}

Rate Limit

Request

Response

Header Keys

HTTP Status Codes

Products

Resources

Miscellaneous