«invalid_request» — это не ошибка, это квест для человека в 02:00.

«invalid_request» — это не ошибка, это квест для человека в 02:00.

Если API отвечает голым кодом без причины, поля и следующего шага, вы сжигаете время на догадки. Для DX это критично: главный KPI онбординга — time to first successful call. Чем быстрее разработчик получает первый 200 OK, тем выше шанс, что он останется.

Что должно быть в нормальной ошибке:
- machine-readable code
- human-readable message
- что именно сломалось: `field`, `expected`, `received`
- что делать дальше: `fix`, `retry`, `contact`
- request id для саппорта и логов

RFC 9457 как раз про это: не просто «ошибка», а structured problem details. Примерный формат:
```json
{
"type": "https://api.example.com/problems/invalid-token",
"title": "Invalid token",
"status": 401,
"detail": "Token expired",
"instance": "req_7f3a",
"errors": [{"field":"token","message":"expired"}]
}
```

Парадокс: «скучный» API — лучший API. Предсказуемые ошибки, стабильные статусы, одинаковая схема ответов экономят часы поддержки и делают интеграцию почти безболезненной. 🛠️