Ошибки¶

Ошибка — всегда объект error и не-2xx статус. Успех — тело напрямую. Различать по статусу, не по форме тела.

{
  "error": {
    "code": "invalid_request",
    "message": "unknown kind \"film\"; allowed: movie, series, mini_series, tv_show, anime, cartoon, short",
    "field": "kind"
  }
}

поле	всегда	что это
`code`	да	машинный код, `snake_case`; на него и завязывайтесь
`message`	да	человеческое объяснение
`field`	нет	параметр, из-за которого отказ
`allowed`	нет	список допустимых значений
`hint`	нет	подсказка «возможно, вы имели в виду»

Ветвитесь по code, а не по HTTP-статусу и не по тексту: статус один на несколько причин, текст может уточняться.

Таблица кодов¶

статус	`code`	когда возникает	что делать
`400`	`invalid_request`	неизвестное значение перечисления, нечисловой `limit`, снятый параметр, курсор вместе с `sort=random`	прочитать `field` и `allowed`, исправить запрос
`401`	`unauthorized`	нет заголовка `X-API-Key`, ключ неизвестен или отозван	проверить заголовок и сам ключ
`403`	`forbidden`	ключ есть, но прав на этот ресурс нет	запросить доступ у владельца
`404`	`not_found`	идентификатора нет в базе; подборки с таким `slug` нет	проверить тип и номер; при `/ids` это значит, что связка не построена
`409`	`conflict`	запись противоречит уже существующей	перечитать текущее состояние
`429`	`rate_limited`	превышен предел в секунду или дневная квота	подождать `Retry-After` секунд
`500`	`internal`	сбой на нашей стороне	повторить позже; если повторяется — сообщить
`502`	`source_unavailable`	внешний источник не ответил при заполнении данных	повторить позже

Валидация подсказывает¶

Ошибки перечислений несут список допустимых значений и, если опечатка похожа на реальное имя, подсказку:

curl -H "X-API-Key: $KINODATA_KEY" "https://api.kinodata.space/v1.2/ids/tmbd/27205"

{
  "error": {
    "code": "invalid_request",
    "message": "unknown type \"tmbd\"",
    "field": "type",
    "allowed": ["imdb", "kp", "tmdb", "tmdb_tv", "kinorium"],
    "hint": "did you mean \"tmdb\"?"
  }
}

Подсказка учитывает перестановку букв, поэтому tmbd находит tmdb.

Повторные попытки¶

код	повторять
`429`	да, после `Retry-After`
`500`, `502`	да, с экспоненциальной задержкой
`400`, `401`, `403`, `404`, `409`	нет — запрос не станет корректным сам по себе

Все методы справочника — GET, они идемпотентны: повтор безопасен и ничего не меняет.