Ошибки и лимиты

Что значит каждый статус, сколько запросов можно сделать и какие запросы считаются.

Вид ошибки

На любой статус, кроме 200, приходит JSON с кодом и пояснением. Проверяйте code: пояснение message — для разработчика, по-английски, и может меняться.

Ответ400 Bad Requestданные 2026.01.02 v.219

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
X-Data-Version: 2026.01.02 v.219

{
  "error": {"code": "bad_parameter", "message": "'count' must be in 1..50"}
}

Статусы и коды

Статус	Код	Когда
400	bad_parameter	Параметр неверный, неизвестный или не того типа; строка запроса не в UTF-8; JSON вложен глубже 16 уровней.
400	bad_request	Тело запроса не удалось прочитать.
401	unauthorized	Нет ключа, или ключ неизвестен, отключён, истёк. В ответе заголовок `WWW-Authenticate: Token`.
403	forbidden	Ключу нельзя этот маршрут, этот сайт или этот IP-адрес. Например, публичный ключ на `/v1/details` или запрос не с сайта из списка ключа.
404	not_found	Запрошенного объекта нет в ГАР.
404	parent_not_found	Объекта из `parent` нет в ГАР.
405	method_not_allowed	Метод не тот. Разрешённые — в заголовке `Allow`.
413	body_too_large	Тело запроса больше 64 КБ.
415	unsupported_media_type	POST без `Content-Type: application/json`.
429	daily_limit	Дневной лимит исчерпан. `Retry-After` — секунды до полуночи по Москве, когда счёт начнётся заново.
429	rate_limit	Слишком много запросов в секунду. `Retry-After: 1`.
500	internal	Ошибка на нашей стороне. Не считается.
503	not_ready	Сервер ещё не готов. Повторите запрос через несколько секунд. Не считается.
503	geo_not_loaded, lookup_not_loaded	Координаты или поиск по коду временно недоступны. Не считается.

Нет ключа

Ответ401 Unauthorizedданные 2026.01.02 v.219

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
WWW-Authenticate: Token
X-Data-Version: 2026.01.02 v.219

{
  "error": {
    "code": "unauthorized",
    "message": "an API key is needed: Authorization: Token <key>"
  }
}

Публичный ключ на маршруте для секретного

Ответ403 Forbiddenданные 2026.01.02 v.219

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
X-Data-Version: 2026.01.02 v.219

{
  "error": {
    "code": "forbidden",
    "message": "the API key may not call this route from this site or address"
  }
}

Дневной лимит

Ответ429 Too Many Requestsданные 2026.01.02 v.219

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 75521
X-Data-Version: 2026.01.02 v.219

{
  "error": {
    "code": "daily_limit",
    "message": "the daily limit of the API key or its account is reached"
  }
}

Лимит в секунду

Ответ429 Too Many Requestsданные 2026.01.02 v.219

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 1
X-Data-Version: 2026.01.02 v.219

{
  "error": {
    "code": "rate_limit",
    "message": "too many requests per second for the API key"
  }
}

Лимиты

Что	Сколько
Запросов в день на аккаунт	20 000
Запросов в секунду на ключ	30
Запросов в день на публичный ключ без своего лимита	10 000

День — московский: счёт начинается заново в 00:00 по Москве. Лимит в секунду допускает короткий всплеск, не больше секунды запросов сразу. Нужно больше — напишите нам.

Что считается запросом

Каждый запрос с известным ключом, который прошёл проверки, к поиску, адресу по коду и по координатам — с любым ответом, кроме 5xx. Ответы 400 и 404 тоже считаются; ошибка на нашей стороне — нет.

Не считаются:

запросы, которые не прошли проверки: без ключа, с чужого сайта, сверх лимита (401, 403, 429);
status/address и iplocate/address совместимого режима;
предварительные запросы браузера (OPTIONS);
/health, /ready, /version.

Свой API и совместимый режим считаются вместе: лимит один.

Совместимый режим

Ошибки совместимого режима — в его привычном виде и с его статусами:

Статус	Когда
401	Нет ключа.
403	Ключ неизвестен, отключён или истёк; маршрут, сайт или IP-адрес не разрешён; дневной лимит исчерпан.
429	Слишком много запросов в секунду.
400, 405, 413, 415	Как в своём API.
503	Сервер ещё не готов.

Ответ401 Unauthorizedданные 2026.01.02 v.219

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
WWW-Authenticate: Token
X-Data-Version: 2026.01.02 v.219

{
  "family": "CLIENT_ERROR",
  "reason": "Unauthorized",
  "message": "an API key is needed: Authorization: Token <key>"
}

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

Заголовок	Что это
X-Data-Version	Версия данных ГАР, на которых дан ответ. Есть в каждом ответе.
Server-Timing	`engine;dur=<мс>` — сколько миллисекунд работал поисковый движок на сервере, без сети. В ответах поиска, адреса по коду и по координатам.
Retry-After	Через сколько секунд повторить запрос после 429.
WWW-Authenticate	`Token` в ответе 401.

Браузеру доступны X-Data-Version, Retry-After и Server-Timing (Access-Control-Expose-Headers).