Как проектировать согласованные ответы об ошибках и сообщать об ошибках валидации?

Question

IT Interview Practice · Accepted Answer

Хороший ответ об ошибке делает две вещи: использует **правильный HTTP-код состояния** (машиночитаемый сигнал) и возвращает **согласованное структурированное тело**, с которым разработчик может что-то сделать. Несогласованные формы ошибок — один из крупнейших источников боли на стороне клиента.

## Используйте стандартный формат ошибок: RFC 7807 (problem+json)

RFC 7807 определяет стандартное тело «problem details» с выделенным media type, поэтому каждая ошибка в вашем API выглядит одинаково:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — URI, идентифицирующий категорию ошибки (разыменовывается в документацию).
- `title` — короткое человекочитаемое резюме (стабильное для каждого `type`).
- `status` — HTTP-статус, продублированный для удобства.
- `detail` — конкретное объяснение для *этого* случая.
- `instance` — в каком запросе/ресурсе это произошло.

## Ошибки валидации: сообщайте все сразу

Для валидации формы/полей верните `422` (или `400`) и **массив ошибок по полям**, чтобы клиент мог подсветить каждое плохое поле за один проход — а не по одной ошибке за раз:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Принципы

```text
✓ Same body shape for every error (one code path on the client)
✓ A stable machine-readable code (type/code) — clients branch on this, not on prose
✓ Human-readable message for developers/logs
✗ Never leak stack traces, SQL, or internal paths to clients
```

## Почему это важно

Проектирование ошибок — это место, где API тихо преуспевают или проваливаются в реальном мире: happy path прост, но потребители тратят большую часть времени отладки на пути ошибок, и несогласованный или расплывчатый контракт ошибок делает интеграцию мучительной. Интервьюеры используют это, чтобы проверить две вещи. Во-первых, **код состояния плюс структурированное тело работают вместе** — статус это грубый сигнал для инструментов и повторов, тело несёт действенную деталь — а не антипаттерн `200 OK` с ошибкой внутри. Во-вторых, **стабильный, машиночитаемый код ошибки** (через `type` из RFC 7807 или поле `code`), чтобы клиенты ветвились по `"insufficient_funds"`, а не сопоставляли строку английского сообщения, которое могут переформулировать или локализовать. Возврат всех ошибок валидации сразу и отказ от утечки внутренних деталей вроде stack trace завершают ответ, показывающий, что вы строили API, которые другим командам действительно приходилось потреблять.

Используйте стандартный формат ошибок: RFC 7807 (problem+json)

Ошибки валидации: сообщайте все сразу

Принципы

Почему это важно

Похожие вопросы