Стендап Сьогодні
📢 Канал в Telegram @stendap_sogodni
🦣 @stendap_sogodni@shevtsov.me в Федиверсі

🤖🚫 AI-free content. This post is 100% written by a human, as is everything on my blog. Enjoy!

14.10.2025

Правильні помилки в API

Чи знаєте ви, що існує аж цілий RFC про повернення помилок з API? Ось: RFC 9457 - Problem Details for HTTP APIs. Виглядають ці помилки трохи дивно, як на мене:

{
  "type": "https://docs.leonid.codes/no-mana",
  "title": "We require more mana",
  "detail": "Teleportation spell requires 20 mana, but you have 15",
  "spell": "teleportation",
  "mana_required": 20,
  "mana_available": 15
}

Тут type - це URL, який може вказувати на документацію про помилку. Що мені дуже подобається. title - назва помилки, яка є незмінною. А detail - текстове пояснення, яке вже може містити подробиці про конкретний випадок. Нарешті, окрім цих полів можна додавати будь-які власні.

Альтернативою є формат помилок зі специфікації JSON API. Причому назва JSON API може й загальна, але специфікація досить конкретна та суворо обмежує структуру відповідей. Щодо помилок, то вона вимагає на верхньому рівні ключ errors, а в середині — цілий масив обʼєктів помилок — кожна з яких недалека від RFC 9457.

Логіка така, що в такому повідомленні є й частини, які може прочитати людина, зокрема й в журналі, а також є інформація для машинної обробки. Але чого тут немає, так це success: true або status: "ok", які я звик бачити. Знаєте, чому?

Бо найважливіша частина повідомлення про помилку — це статус HTTP. Яких у нас великий вибір. Та вкрай важливо визначити та передати доцільний статус вашої помилки. Тоді зміст відповіді вже несе суто уточнювальний характер.

Є така тенденція ігнорувати статус та дивитися тільки на зміст. Наприклад, на фронтенді так може “простіше” робити. Чув і такі думки, що статуси HTTP тільки для критичних помилок, а якщо сервер “в тямі”, то може вже давати 200-й із success: false, errors: .... Це все від нерозуміння основ протоколу HTTP.

Все це особливо відчутно у статично типізованій мові, де потрібно знати структуру відповіді до того, як ти її прочитаєш. Та й взагалі динамічна типізація погано впливає на якість API, бо дозволяє безтурботно повертати будь-що будь-де.

13.10.2025 React Native: екосистема на …