Аутентификация

Каждый запрос несёт ключ в заголовке X-API-Key:

curl -H "X-API-Key: kd_live_b62a29f3…" \
  "https://api.kinodata.space/v1.2/ids/kp/447301"

Единственное исключение — /health, он отвечает без ключа.

Что бывает не так

статус	код	когда
401	unauthorized	заголовка нет, ключ неизвестен или отозван
429	rate_limited	превышен предел в секунду или дневная квота

{ "error": { "code": "unauthorized", "message": "missing api key" } }

Пределы ключа

У ключа два независимых предела: в секунду и в сутки. Ноль на любой оси означает «без предела».

тариф	запросов в секунду	запросов в сутки
free	60	10 000
pro	600	1 000 000
unlimited	без предела	без предела

Свои значения смотрите в заголовках ответа. Они приходят, когда у ключа задан предел в секунду; у ключа без пределов заголовков нет — считать нечего:

заголовок	значение
X-RateLimit-Limit	предел на текущем окне
X-RateLimit-Remaining	сколько осталось
X-RateLimit-Reset	Unix-время сброса окна
Retry-After	секунд до следующей попытки; приходит только при 429

Сообщение при 429 говорит, какой именно предел сработал:

{ "error": { "code": "rate_limited", "message": "rate limit exceeded" } }

rate limit exceeded — предел в секунду, quota limit exceeded — дневная квота.

Служебные заголовки

С каждым ответом приходят два заголовка, полезных при разборе проблем:

заголовок	значение
X-Api-Version	версия, ответившая на запрос
X-Request-Id	идентификатор запроса — его стоит приложить к обращению

Хранение ключа

Ключ даёт доступ к данным целиком. Держите его на сервере, не в клиентском коде и не в репозитории: в браузере он виден каждому, кто откроет инструменты разработчика.