Як писати повідомлення про помилки Clear API англійською

Повідомлення про помилку API — це частина англійського тексту. Більшість розробників не думають про це таким чином — вони думають про це як про технічний артефакт, код стану, поле JSON. Але в той момент, коли розробник прочитає ваше повідомлення про помилку о 23:00, зневаджуючи виробничу проблему, це стає комунікацією. Ясне повідомлення знижує час. Погана сторінка спричиняє плутанину, збільшує кількість квитків на підтримку і знижує довіру до вашого API.

У цьому підручнику ви дізнаєтесь про принципи написання ефективних повідомлень про помилки API англійською мовою, з реальними прикладами і фразами, які працюють.

---

4) 4-х ступенева система оцінки якості

Правильним повідомленням про помилку API є:

1. ** Специфічний ** — він говорить розробнику, що саме не так
2. ** Actionable ** — це дає розробнику поради щодо подальших дій
3. ** Не звинувачувати ** — це не робить розробника дурним
4. ** Послідовний ** — він відповідає передбачуваному формату у вашому API

Більшість поганих повідомлень про помилки не відповідають вимогам щодо специфічності і можливості виконання дії. « Сталася помилка » не відповідає вимогам щодо обох.

---

Структура відповіді на помилку API

Відповідь на помилку з хорошою структурою у JSON зазвичай містить:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The 'email' field must be a valid email address.",
    "details": [
      {
        "field": "email",
        "issue": "Value 'user@' is not a valid email address."
      }
    ],
    "request_id": "req_8Kx92mPzA1"
  }
}

Поле message є місцем, де англійське письмо має найбільше значення. Давайте подивимося, як його добре написати.

---

Запис поля повідомлення про помилку

Будь конкретним про те, що не вдалося

** Погана: ** * « Некоректний вхід. » * ** Добре: ** “Параметр « дата_ початку » має бути у форматі ISO 8601 (наприклад, « 2026- 06- 23 »).”

** Погана: ** * « Спроба автентифікації зазнала невдачі. » * ** Добрий: ** * “Наданий ключ API невірний або був відкликаний. Перевірте ваш ключ на панелі інструментів за адресою https://app.example.com/settings/api-keys.”*

** Погана: ** * « Ресурс не знайдено. » * ** Добре: ** “Не знайдено проекту з ідентифікатором « proj_ abc123 ». Проект, можливо, було вилучено або його ідентифікатор неправильний.»

Зауважте на шаблоні: дайте назву полю або ресурсу, описайте проблему, і (якщо це можливо) наведіть приклад коректного значення.

Використовувати активний голос і пряму мову

Пасивний голос робить повідомлення про помилку нечіткими і важкими для виконання.

** Пасивно (уникнути): ** * « Запит не вдалося обробити через відсутність певних полів ». * ** Активний (бажано): ** * « У вашому запиті відсутні обов’ язкові поля: « ім’ я » і « валюта ». » *

** Пасивно (уникнути): ** « Обмеження швидкості було перевищено. » ** Активний (краще): ** * “Ви перевищили обмеження швидкості, яке становить 100 запитів за хвилину. Ваш обмежувач скидається о 14:32 UTC.”*

Запропонувати наступний крок

Найціннішим, що може зробити повідомлення про помилку, є те, що воно дає розробнику зрозуміти, що робити далі.

** Ключові фрази для повідомлень, що вимагають дій: **

• «Повторіть запит після…»
• «Відкрийте для себе цінність»
• Перевірте це… перед викликом цієї кінцевої точки
• «Див. документацію на [URL] для списку чинних значень.»
• Процитовано 2011-03-14.  «Contact support at support@example.com if this issue persists.» (англійською)

Використовувати послідовну структуру речення

Якщо ваші помилки 400 відповідають одному шаблону, а ваші помилки 403 — іншому, розробникам слід подумати про форматування, а не про зміст. Встановіть шаблон і тримайтеся його.

** Шаблон для помилок перевірки: **

• ”« [назва_ поля] » [поле або параметр] [опис проблеми]. [Приклад коректного значення або посилання на документацію].” *

** Шаблон для помилок прав доступу: **

• « Ваш ключ API не має прав на [дія]. [Як отримати права або яку роль потрібно]. » *

** Шаблон для помилок обмеження швидкості: **

• “Ви перевищили обмеження [типу] [обмеження] [одиниць]. [Коли його скинути або як його збільшити].” *

---

HTTP Status Codes and the English They Imply (англійською)

Розуміння кодів стану допоможе вам написати правильний текст повідомлення:

• ** 400 Поганий запит ** — клієнт надіслав щось неправильне. У повідомленні слід пояснити, що і як виправити.
• ** 401 Неавторизовано ** — клієнт не автентифікований. Скажи їм, як здійснити автентифікацію.
• ** 403 Заборонено ** — клієнт розпізнано, але йому не вистачає прав. Поясніть, які права потрібні.
• ** 404 Не знайдено ** — ресурсу не існує. Підтверджує ідентифікатор і пропонує перевірити, чи не було його вилучено.
• ** 409 Conflict** — конфлікт станів (наприклад, дублікат запису). Поясни, що вже існує.
• ** 422 Необроблювана сутність ** — семантично неправильний вхід (навіть якщо синтаксис коректний). Список обмежень, які було порушено.
• ** 429 Забагато запитів ** — обмежена швидкість. Вкажіть межу і час скасування.
• ** 500 Внутрішня помилка сервера ** — помилка на стороні сервера. Не показувати внутрішні дані; надати ідентифікатор запиту для підтримки.

---

Анти-патерни, яких слід уникати

Складні сліди в виробництві

Ніколи не показувати внутрішні сліди стека користувачам API. Вони розкривають деталі реалізації і є безглуздими для більшості розробників. Замість: “Встановлена неочікувана помилка. Ідентифікатор джерела: req_9Lm4xZp7B2. Якщо це не зміниться, зверніться до підтримки.”

Занадто технічні внутрішні назви

** Погана: ** * “NullPointerException in PaymentGatewayAdapter. processCharge ()” * ** Добре: ** * “Заряд не вдалося обробити. Будь ласка, перевірте, чи поле «сума» більше нуля і чи правильний спосіб оплати приєднано до клієнта. ”*

«Щось пішло не так»

Це повідомлення не містить жодної інформації. Це повідомлення про помилку, еквівалентне погнуті плечима. Кожна помилка, яку повертає ваш API, повинна бути достатньо конкретною, щоб розробник міг виконати відповідну дію.

Незв’ язна прописка і пунктуація

Ваші повідомлення про помилки є частиною вашої поверхні API. Відносяться до них як до коду. Якщо деякі повідомлення закінчуються крапкою, а інші — ні, якщо деякі повідомлення написано у регістрі речень, а інші — у регістрі заголовків, розробники помітять невідповідність і зменшать довіру до вашого API.

---

Ключовий словник

• ** Код помилки ** — машинно-читальний ідентифікатор типу помилки (наприклад, INVALID_PARAMETER )
• ** Повідомлення про помилку ** — опис, який можна прочитати
• ** ІД запиту ** — унікальний ідентифікатор для певного виклику API, корисний для зневадження
• ** Обмеження швидкості ** — максимальна кількість дозволених запитів у часовому вікні
• ** Перевірка ** — перевірка відповідності вхідних даних необхідним обмеженням
• ** Обмеження ** — правило, яке має бути виконано при введенні (наприклад, « має бути додатним », « не більше 255 символів »)
• Идемотент - операция, которую можно безопасно повторить без побочных эффектов
• ** Retry- After ** — заголовок HTTP, який вказує, коли клієнт може повторити спробу після обмеження швидкості

---

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

Наприклад, англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська

Написання ефективних повідомлень про помилки API не просто про те, що * що * пішло не так; це про те, щоб повідомити цю інформацію чітко і конструктивно. Для розробників, чия перша мова не є англійською, це може бути особливо складним. Крім простого перекладу технічних термінів, існує тонке мистецтво формулювання помилок таким чином, щоб їх було легко зрозуміти, уникнути неоднозначності і заохочувати швидке розв’язання. Неправильно сформоване повідомлення про помилку може призвести до розчарування сеансів зневадження, марного часу, і, врешті-решт, негативного досвіду розробника - чогось, чого ми хочемо уникнути за будь-яку ціну.

Одним з ключових аспектів, які часто ігноруються, є використання більш формальної, точної мови при створенні цих повідомлень. Хоча неформальна фраза може здатися швидшою спочатку, вона ризикує ввести непотрібну складність для когось, хто все ще будує свій професійний англійський словник. Наприклад, замість повідомлення « Щось пішло не так!» (це повідомлення є нечітким і не надає жодних вказівок), розгляньте повідомлення « Запит зазнав невдачі через помилку перевірки: не було надано обов’ язкове поле « адреса електронної пошти » ». Це повідомлення негайно повідомить розробника про те, що слід виправити — йому слід додати адресу електронної пошти. Аналогічно, в повідомленні Slack, що пояснює помилку, уникай сказати «Це пошкоджено!» і замість цього пиши: «Я зіткнувся з помилкою 400 Bad Request при спробі створити нового користувача. Сервер повернув помилку, що вказує на відсутність поля «ім’я користувача»

Розглянемо практичний сценарій: під час перегляду коду ви побачили коментар від колеги, у якому йдеться: « Це повертає помилку 500 — потрібні більше відомостей ». Корисною і професійною відповіддю буде: « Я погоджуюся; хоча помилка 500 вказує на проблему на стороні сервера, вона не вказує на її корінну причину. Додання команди журналу до обробника для запису певного типу винятку і повідомлення значно полегшить зневадження. » Це не лише демонструє розуміння проблеми, але також і активно пропонує рішення — додавання більш детального журналу є найкращим способом, з яким багато розробників, можливо, ще не знайомі з точки зору його точної англійської термінології. Пам’ ятайте, що ключовим є надання контексту, а не лише самого коду помилки.

Нарешті, при написанні описів PR для помилок, зосередьтеся на тому, * чому * виникла проблема і які кроки були зроблені для її вирішення. Замість « Виправлено помилку 500 » спробуйте: « Виправлено внутрішню помилку сервера 500, спричинену необробленим винятком під час розпізнавання користувача. Впроваджено надійну обробку помилок з докладним веденням журналу і додано умовну перевірку чинних даних реєстрації перед продовженням роботи. ” Цей рівень деталізації, з використанням чіткого і описового словника, забезпечує, що кожен, хто переглядає зміни — навіть ті, хто не має досвіду роботи з англійською мовою — зможе швидко зрозуміти проблему і її рішення.