Опубликовано в Профессии

Ошибки API: как договориться о статусах и формате ответа

Одна фигурка указывает на повреждённое колесо тележки, а другая держит целое колесо.

Время чтения: 5 мин.

Формат ошибки API должен помогать клиенту выбрать следующее действие и при этом не раскрывать внутреннее устройство сервиса. Для этого договорись о статусе, стабильном типе проблемы и безопасном сообщении. Если каждый обработчик придумывает собственный ответ, клиенту придётся угадывать причины по тексту.

Возьмём учебный сервис бронирования комнаты. Пользователь передал неправильный интервал, попытался занять уже занятое время либо столкнулся с недоступной базой. Это разные ситуации. Ниже разберём, как описать их в одном контракте и проверить, что сервер соблюдает договорённость.

Начни с причины и следующего действия

Выпиши основные ошибки через поведение пользователя. Неправильную дату можно исправить. Конфликт времени требует выбрать другой интервал или заново получить состояние. Сбой зависимости обычно нельзя исправить изменением поля формы. Эти различия должны сохраняться в ответах.

Не начинай с длинного общего списка исключений из библиотек. Они описывают устройство реализации, а клиенту нужен смысл операции. Ошибка соединения с базой может быть одной из внутренних причин общего публичного отказа выполнить запрос.

Для каждой ситуации запиши три вещи: что произошло с данными, что получает клиент и что он может сделать дальше. Например, отклонённая бронь не сохраняется, ответ сообщает о конфликте, а интерфейс предлагает обновить доступные интервалы.

Отдельно обозначь неопределённый результат. Если подтверждение потерялось после выполнения операции, простой повтор может иметь последствия. В таком случае контракту понадобится способ проверить итог или безопасно связать повтор с исходным действием. Формат ошибки сам по себе этого не обеспечивает.

Выбери статусы по смыслу HTTP

Семантика HTTP описана в RFC 9110. Для контракта полезно различать неправильный запрос, отсутствие необходимых учётных данных, запрет действия, отсутствие ресурса и конфликт с текущим состоянием. Не назначай один статус всем неуспешным операциям ради простоты обработчика.

В учебном бронировании можно выбрать 400 для согласованной группы ошибок входа и 409 для занятого интервала. Это решение примера, которое нужно документировать; иной API может отдельно использовать 422 для подходящих случаев. Клиент и сервер должны одинаково понимать выбранное правило.

Для отсутствующего объекта и недоступного чужого объекта возможна осознанная политика сокрытия существования. Выбери её заранее вместе с правилами доступа. Не позволяй разным маршрутам случайно раскрывать то, что другой маршрут скрывает.

Успешный статус с полем об ошибке в теле затрудняет работу обычных HTTP-клиентов и наблюдение за результатами. Статус и смысл тела должны согласовываться. В проверках наблюдай оба, чтобы изменение одного обработчика не создало особое исключение.

Рука опускает синий конверт с треугольным значком в отделение сортировщика конвертов по форме значков.

Определи стабильную машинную часть

Клиент не должен разбирать человеческую фразу, чтобы отличить конфликт времени от ошибки даты. Текст может поменяться после редактуры или перевода. Выдели устойчивый тип проблемы и необходимые структурированные сведения.

RFC 9457 описывает Problem Details с полями type, title, status, detail и instance. Формат также позволяет задавать расширения. Его можно выбрать как основу, если он подходит контракту приложения и существующим клиентам.

Для учебного проекта опиши конкретный тип конфликта и допустимые сведения о нём. Например, не нужно возвращать владельца чужой брони, чтобы сообщить, что время уже занято. Для ошибки поля можно определить расширение с названием поля и машинным кодом причины.

Не требуй от клиента автоматически открывать ссылку типа проблемы при каждом отказе. Договорённость о типе должна работать независимо от доступности страницы документации. Описание полезно разработчику, а основной путь обработки должен оставаться предсказуемым.

Раздели пояснение пользователю и диагностику

Короткое публичное сообщение должно объяснять ситуацию в терминах действия. «Выбранное время уже занято» полезнее имени SQL-ограничения. «Не удалось сохранить бронь» честнее пустого успешного результата после внутреннего сбоя.

OWASP рекомендует контролировать раскрытие диагностических сведений в ошибках. Полный стек, внутренний путь файла и строка подключения к базе не нужны клиентскому ответу. Для исследования ошибки оставляй безопасные сведения на стороне сервера.

Свяжи ответ с журналом через идентификатор запроса или события, если это принято в проекте. Сам идентификатор не должен содержать секреты. По нему разработчик сможет найти диагностическую запись без копирования внутренних деталей в публичное поле detail.

Отдельно проверь ожидаемую ошибку и необработанное исключение. Общий обработчик должен сохранять согласованную форму ответа и не возвращать случайную страницу framework. При этом скрытие подробностей от клиента не должно означать потерю причины в доступной разработчикам диагностике.

Рука придерживает синюю коробку перед открытым шкафчиком, внутри которого стоит похожая коробка.

Опиши повтор и изменение состояния

Для каждого важного отказа спроси, сохранилась ли операция. Невалидный интервал должен быть отклонён до создания брони. Конфликт должен оставлять существующую бронь целой. Сбой после частичного действия требует отдельного правила восстановления.

Не добавляй универсальную кнопку «повторить» ко всем ошибкам. Исправляемый ввод, запрет прав и временный отказ зависимости требуют разных действий. Автоматический повтор особенно важно согласовать для операций, создающих внешние последствия.

В учебном API можно начать с ограниченного набора состояний и простого способа получить результат создания по известному идентификатору. Если этого пока нет, честно опиши пределы безопасного повтора. Не обещай клиенту гарантию, которую сервер не может проверить.

Проверь повторное удаление или отмену отдельно. Выбранный результат должен соответствовать документированному контракту, а не зависеть от того, какая библиотечная ошибка первой дошла до обработчика. Это позволит клиенту обходиться без специальных догадок для каждого пути.

Для одного типа ошибки запиши минимальный пример ответа в документации проекта и проверь его общей схемой, если она уже используется. Пример должен совпадать с реальным обработчиком. Иначе клиент начнёт поддерживать форму, которая существует только в описании.

Проверь контракт примерами ответов

Подготовь по одному запросу на каждую существенную причину отказа. Сохрани ожидаемые статус, тип проблемы, допустимые поля и состояние данных. Для сообщений проверяй смысл и отсутствие недопустимых сведений, не привязывая все тесты к пунктуации одной фразы.

Добавь проверку общей ошибки, которая возникает вне обычного успешного пути. Например, тестовая зависимость может вернуть известный сбой. Сервер должен преобразовать его в согласованный публичный ответ, сохранив возможность диагностики.

После изменения формата прогони и существующих клиентов. Добавление поля и переименование машинного типа имеют разные последствия. Если тип уже используется в логике клиента, его изменение нужно рассматривать как изменение контракта.

Итогом станет небольшой перечень ошибок с причинами, ответами и действиями. На совместный разбор принеси этот перечень и реальные примеры из тестового окружения. Ментор сможет проверить, где сообщение помогает пользователю, а где ответ скрывает неясное состояние операции.

Проверь контракт ошибок с backend-ментором

Подготовь причины отказов, ответы API и действия клиента. Выбери специалиста, с которым можно обсудить конкретные примеры и состояние данных.

Выбрать ментора