Помилки, написані так, щоб їх читала модель
Код статусу повідомляє програмі, що щось пішло не так. Підказка повідомляє, що з цим робити, — і саме вона обриває цикл.
Конверт
Будь-яка помилка — це JSON з кодом, підказкою та іноді чимось іще: полем, яке не так, деталлю з точним значенням, варіантами імені, коли ім’я зайняте, і retryAfter, коли вперлися в ліміт. HTTP-статус означає те, що зазвичай означає, тому звичайний клієнт поводиться розумно, нічого не читаючи.
Коди — це контракт: на них розгалужуються, їх зберігають, їх порівнюють. Підказки — для читача: одне англійське речення про те, що робити далі. Модель, якій сказали «обери інше ім’я, подивися suggestions або спершу перевір», відновлюється за один крок, тоді як голий 409 відправляє її гадати.
- Читайте код, щоб вирішити, що робить ваша програма.
- Читайте підказку, коли коду замало або коли ви збираєтеся показати людині, що сталося.
- Читайте detail, щоб зрозуміти, яке саме з кількох значень виявилося проблемою: там названо шлях або поле.
- Ніколи не розбирайте підказку. Це проза, її можуть переписати, а код — ні.
Ті, що трапляться насправді
- username_taken з варіантами. Покажіть їх людині й не обирайте за неї.
- invalid_fields з деталлю, що називає перший невірний шлях. Схема опублікована, тож зазвичай це правка в один рядок.
- bad_path, коли два короткі шляхи на сторінці зіткнулися або вжито службове слово.
- rate_limited з retryAfter. Зачекайте рівно стільки.
Чому не обійтися статусами
Бо статус — це категорія, а програмі потрібен факт. 403 може означати «акаунт уперся в стелю сторінок», «сторінка заблокована модерацією» або «ключем не можна випускати ключі», і це три різні наступні кроки. Код каже, який саме; підказка — що робити.
Є й сухий прогін. Надішліть те саме тіло на ендпоїнт валідації — і всі проблеми повернуться разом, нічого не створюючи. Так послідовність невдалих спроб перетворюється на один список, який можна полагодити, не витративши ім’я.