Средний ~24 мин чтения

Обработка ошибок в API

Урок 4 из 5 в курсе Проектирование REST API

Обработка ошибок в API

правильная обработка ошибок делает API предсказуемым: клиент понимает, что пошло не так и как реагировать.

Почему это важно: Непоследовательная обработка ошибок — одна из главных жалоб разработчиков на API. Клиенты вынуждены разбирать нестандартные форматы и угадывать причину ошибки.

Главная идея

Ошибки API — это тоже контракт: правильный статус-код, понятное сообщение, machine-readable код ошибки и детали для диагностики.

Как это выглядит на практике

  1. Клиент отправляет POST /orders с невалидными данными.
  2. Сервер возвращает 422 Unprocessable Entity.
  3. Тело ответа содержит JSON с кодом ошибки, сообщением и списком полей с ошибками.
  4. Клиент показывает конкретные сообщения под полями формы.

Что происходит под капотом

  • 4xx — ошибки клиента (неверный запрос, нет авторизации, ресурс не найден).
  • 5xx — ошибки сервера (внутренняя ошибка, недоступный сервис).
  • Структура ответа об ошибке должна быть стандартной по всему API: { error: { code, message, details } }.
  • RFC 9457 (Problem Details for HTTP APIs) — стандарт для структурированных ошибок в API.

Типичные ошибки и заблуждения

  • Ошибка: возвращать 200 OK с полем error в теле. Это ломает HTTP-семантику и усложняет клиентскую логику.
  • Ошибка: всегда возвращать 500 при серверной ошибке. Многие ошибки — клиентские (400, 422, 404) и должны возвращаться как 4xx.
  • Ошибка: сообщение об ошибке достаточно для диагностики. Machine-readable код (например, VALIDATION_ERROR) упрощает автоматическую обработку.
  • Ошибка: детали внутренней ошибки полезны для клиента. Stack trace в ответе — угроза безопасности.

Ключевые выводы

  • Используйте правильные HTTP-статус-коды: 400/422 для клиентских ошибок, 500 для серверных.
  • Стандартизируйте формат ошибок по всему API.
  • Никогда не возвращайте stack trace или внутренние детали в production-ответах.
  • Machine-readable коды ошибок позволяют клиентам обрабатывать их программно.

Термины урока

4xx: класс HTTP-статусов для ошибок клиента.
5xx: класс HTTP-статусов для ошибок сервера.
Error code: машиночитаемый идентификатор типа ошибки.
Validation error: ошибка, вызванная невалидными входными данными.

Связь с работой backend-разработчика

Создайте единый error handler в вашем фреймворке, который стандартизирует формат ошибок. В Rails — rescue_from в ApplicationController; в Express — error-handling middleware.

Мини-разбор реальной ситуации

Мобильное приложение отправляет форму регистрации. API возвращает 500 с HTML-страницей ошибки Rails. Клиент показывает 'Неизвестная ошибка'. Правильное решение: глобальный error handler, возвращающий JSON с 422 и списком невалидных полей.

Что запомнить

  • Ошибки — тоже часть API-контракта; стандартизируйте их формат.
  • Правильный статус-код даёт клиенту контекст без парсинга тела.
  • Никакой внутренней информации в ответах об ошибках для production.

Итог

Предсказуемая обработка ошибок — признак зрелого API. Инвестиция в стандартный формат ошибок возвращается в виде упрощённой интеграции и быстрой диагностики.