Главная/Начало работы/Ошибки и соглашения ENУКРРУС API-справочник (ReDoc) ↗

Ошибки и соглашения

Форматы ответов, что стабильно, кеширование, лимиты.

Формат ошибки

Каждая неудача выглядит одинаково:

{
  "error": {
    "code": "language_not_found",
    "message": "Unknown language code: 'xx-YY'",
    "details": { "language": "xx-YY" }
  }
}

code — это контракт: стабильный, snake_case, безопасный для ветвления. message для людей и может быть переформулирован в любой момент. details несёт значения, на которых споткнулись, и присутствует, когда они есть.

Полный перечень — Error Codes.

Коды статусов

Статус Когда
200 Успех — включая батч, где часть элементов упала
404 language_not_found, provider_not_found
409 language_unsupported — оба существуют, паре отказано
413 Тело запроса свыше 256 КБ
422 Некорректный запрос (типы, батч свыше 500 пар)
503 Сервис не готов — база или каталог недоступны

Почему 409, а не 404 для неподдерживаемой пары

Оба названных ресурса существуют; отказано именно их комбинации. Вызывающий, вечно ретраящий тот же 404, делал бы неверный вывод. На практике /v1/resolve отдаёт это в теле как supported: false, а не бросает ошибку, так что пару можно залогировать и идти дальше.

Что стабильно

Стабильно, меняется только с новой версией пути:

  • пути эндпоинтов и имена query-параметров
  • имена полей в ответах
  • значения error.code
  • значения match

Нестабильно — не парсите:

  • текст message
  • порядок aliases за пределами «отсортировано»
  • точное количество чего угодно

Новые необязательные поля могут появиться в любой момент. Игнорируйте неизвестные поля.

Кеширование

Каталог меняется редко — несколько правок в месяц. Ответы пока не несут Cache-Control, но данные безопасно кешировать у себя на минуты. Если кешируете — кешируйте пару language + code, а не весь ответ.

Внутри сервис держит каталог в памяти и перестраивает его по TTL и сразу после любой записи в админке, так что правка в панели видна уже следующим запросом.

Лимиты

Лимит Значение
Тело запроса 256 КБ
Пар в батче 500 на запрос
Rate limit нет — это публичные данные только на чтение

Correlation id

Пришлите X-Correlation-Id — его вернут и запишут в каждую лог-строку этого запроса. Не пришлёте — сгенерируют. Указывайте его, когда сообщаете о проблеме.

Версионирование

Пути несут /v1. Ломающее изменение означает /v2, работающий рядом с /v1 в течение заранее объявленного окна.

Далее