Розділіть помилки за джерелом
Помилка перевірки даних, відсутня авторизація, перевищення ліміту, тайм-аут і 500 — різні ситуації. Одна загальна відповідь «щось пішло не так» приховує дію, яку може виконати користувач або система.
Спочатку визначте, хто може виправити проблему: користувач, ваш код, зовнішній провайдер або адміністратор. Від цього залежить код стану, повідомлення й повторна спроба.
Перевірка даних і контракт API
Перевіряйте обов’язкові поля, типи, довжину й дозволені значення до зовнішнього запиту. Так користувач отримує конкретну відповідь, а інтеграція не витрачає ліміт запитів на завідомо неправильні дані.
Відповідь також треба валідовувати. Код 200 не гарантує, що дані мають очікувану структуру або що бізнес-операція завершилась.
- Не довіряти полям тільки через типізацію TypeScript.
- Фіксувати версію API й очікувані значення enum.
- Обробляти відсутнє поле без падіння всього процесу.
- Не показувати користувачу необроблений стек помилки.
Тайм-аути, повторні спроби та ліміти
Кожен зовнішній запит має мати тайм-аут. Без нього одна зависла відповідь може утримувати робочий процес або користувацький сценарій невизначено довго.
Повторні спроби виконують із затримкою, обмеженням спроб і jitter. Для 429 враховують Retry-After, а для платежу або операції створення потрібен ключ ідемпотентності.
| Ситуація | Типова реакція |
|---|---|
| 400: помилка даних | Не повторювати, показати конкретне поле |
| 401/403 | Перевірити авторизацію, не маскувати проблему повтором |
| 429 | Зачекати за правилами провайдера |
| Тайм-аут або 5xx | Обмежена повторна спроба для безпечної операції |
Журнали без витоку секретів
Журнал повинен містити ID запиту, категорію кінцевої точки, код стану та тривалість і безпечний контекст. Токен доступу, пароль, дані картки й повні персональні дані в журнал не потрапляють.
Для розподіленого процесу корисний кореляційний ID, який проходить через форму, сервер і зовнішню систему. Він дозволяє знайти один сценарій без пошуку за персональними даними.
- Маскувати токени та файли cookie.
- Зберігати лише потрібний період.
- Розділяти повідомлення користувачу та внутрішню діагностику.
- Додавати сповіщення для критичних повторюваних помилок.
Що бачить користувач
Повідомлення має пояснювати, чи збережені дані й що робити далі. Якщо повтор небезпечний, не просіть натискати кнопку знову без перевірки статусу.
Для довгих операцій покажіть стан і результат асинхронно. Надійність — це не відсутність помилок, а передбачувана поведінка, коли вони відбуваються.
Часті запитання
Чи треба повторювати усі помилки 500?
Ні. Повторюють лише очікувані тимчасові помилки й тільки для операцій, захищених від дублювання.
Що таке ключ ідемпотентності?
Стабільний ключ операції, який допомагає серверу не створити другий результат під час повторного запиту.
Чи можна зберігати відповідь у журналах?
Лише після оцінки даних і маскування секретів; повний набір даних часто зайвий і ризиковий.