Головна/Початок роботи/Помилки та конвенції 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 протягом заздалегідь оголошеного вікна.

Далі