Клієнту API потрібно не лише знати, що пішло не так, а й обробити це програмно. Для цього помилки мають бути в одному передбачуваному форматі на весь API.
Problem Details (RFC 9457, замінив RFC 7807) - стандартний формат з типом application/problem+json:
{
"type": "https://api.example.com/problems/insufficient-funds",
"title": "Недостатньо коштів",
"status": 422,
"detail": "На рахунку 30 грн, а списання - 50 грн.",
"instance": "/payments/8f3a",
"balance": 3000
}
type- URI типу помилки, стабільний ідентифікатор для програмної обробки (бажано - з документацією за цією адресою).title- короткий опис типу, однаковий для всіх його випадків.status- HTTP-код (дублює заголовок для зручності).detail- пояснення саме цього випадку.instance- ідентифікатор конкретного випадку.- Можна додавати власні поля - як
balanceвище чи список помилок валідації за полями.
Принципи, незалежно від формату:
- Правильний HTTP-код - формат тіла його не замінює.
- Машиночитний код помилки (
typeчиcode), а не лише текст: текст змінюють і перекладають, а клієнти на нього не мають покладатися. - Помилки валідації за полями, щоб клієнт підсвітив поля форми.
- Жодних стек-трейсів, SQL і шляхів до файлів у відповіді на проді.
- ID запиту в тілі чи заголовку - щоб знайти помилку в логах за зверненням клієнта.
Докладніше в документації: RFC 9457: Problem Details for HTTP APIs
