Кредиты и лимиты

Два отдельных лимита: кредиты в месяц, это ваша квота, и вызовы в минуту, которые защищают сервис.

Кредиты

Небольшой ответ из базы стоит 1 кредит. Стоимость каждого маршрута указана в таблице цен.
Кредиты списываются только при ответе 2xx. Ошибка ничего не стоит.
Они сбрасываются в первый день вашего периода, раз в месяц. Неиспользованное не переносится.
Сверх квоты вы получаете 429 quota_exceeded. API останавливается, счёт не выставляется.

Лимит в минуту

У каждого плана есть лимит в минуту. Сверх него вы получаете 429 rate_limited с заголовком Retry-After.

Лимиты по планам

	Кредиты в месяц	Вызовы в минуту	История
Start	5 000	30	30 дн.
Creator	30 000	120	90 дн.
Pro	300 000	600	365 дн.
Business	3 000 000	1 800	всё
Enterprise	по договору	по договору	всё

Заголовки каждого ответа

Заголовок	Что означает
`X-RateLimit-Limit`	Разрешённых вызовов в минуту
`X-RateLimit-Remaining`	Оставшихся вызовов в текущую минуту
`X-RateLimit-Reset`	Секунд до сброса минуты
`X-Credits-Cost`	Сколько кредитов стоил этот вызов
`X-Credits-Limit`	Кредиты периода
`X-Credits-Remaining`	Оставшиеся кредиты
`X-Credits-Reset`	Когда сбрасываются кредиты (ISO 8601)
`Retry-After`	Сколько секунд ждать, только при 429 и 503

История

Если вы запрашиваете больше дней, чем разрешает план, ответ обрезается по лимиту плана, а meta.history_cut: true сообщает об этом.

Как повторить вызов

Прочитайте Retry-After, подождите указанное время и попробуйте снова. При quota_exceeded не повторяйте: дождитесь сброса, указанного в X-Credits-Reset.

async function call(url, key) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    const body = await res.json();
    if (res.ok) return body;
    if (body.error.code === "quota_exceeded") throw new Error(body.error.message);
    const wait = Number(res.headers.get("retry-after"));
    if (![429, 503].includes(res.status) || !wait) throw new Error(body.error.message);
    await new Promise((ok) => setTimeout(ok, wait * 1000));
  }
  throw new Error("still busy");
}

import json, time, urllib.error, urllib.request

def call(url, key):
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {key}"})
    for attempt in range(3):
        try:
            with urllib.request.urlopen(req) as res:
                return json.load(res)
        except urllib.error.HTTPError as err:
            body = json.load(err)
            wait = err.headers.get("Retry-After")
            if err.code not in (429, 503) or not wait or body["error"]["code"] == "quota_exceeded":
                raise
            time.sleep(int(wait))
    raise RuntimeError("still busy")

<?php
function call(string $url, string $key): array {
    for ($attempt = 0; $attempt < 3; $attempt++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer $key"]]);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        curl_close($ch);
        $body = json_decode(substr($raw, $size), true);
        if ($status < 400) {
            return $body;
        }
        preg_match("/retry-after: (\\d+)/i", substr($raw, 0, $size), $m);
        if (!in_array($status, [429, 503]) || empty($m[1]) || $body["error"]["code"] === "quota_exceeded") {
            throw new RuntimeException($body["error"]["message"]);
        }
        sleep((int) $m[1]);
    }
    throw new RuntimeException("still busy");
}