Какие типовые ошибки описываются в API контракте и чем они отличаются

Что проверяют

Умеете ли вы как аналитик описать не только успешный сценарий, но и все отказы метода так, чтобы разработчики клиента и сервера поняли их одинаково. Следом обычно спрашивают, чем 401 отличается от 403 и куда отнести бизнес-ошибку вроде «недостаточно средств».

Как отвечать

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

• ошибки клиента (4xx): повтор без изменений не поможет. 400 битый формат, 422 формат верный, но данные нарушают правила, 401 клиент не аутентифицирован, 403 аутентифицирован, но прав нет, 404 ресурса нет, 409 конфликт состояния (дубль, устаревшая версия), 429 превышен лимит, с заголовком Retry-After;
• ошибки сервера (5xx): клиент ни при чём. 500 непредвиденный сбой, 502 и 504 проблемы шлюза или смежной системы, 503 сервис временно недоступен. Для них описывают, можно ли повторять запрос и безопасно ли это (идемпотентность, заголовок Idempotency-Key);
• бизнес-ошибки: запрос технически корректен, но операция запрещена правилами. Для них заводят каталог машиночитаемых кодов вроде INSUFFICIENT_FUNDS поверх HTTP-статуса.

Формат тела лучше взять стандартный: RFC 9457 Problem Details, он заменил RFC 7807. Это application/problem+json с полями type, title, status, detail, instance и расширениями, например массивом ошибок по полям. В OpenAPI ошибки описывают в responses каждой операции, повторяющиеся выносят в components/responses.

Для каждого метода аналитик фиксирует: статус, условие возникновения, код ошибки, текст для пользователя или лога, признак «можно повторить». В gRPC то же делается через статусы INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION, UNAVAILABLE.

Где спотыкаются

Возвращают 200 с полем success: false. Мониторинг, прокси и ретраи клиента такую ошибку не видят, и она теряется.

Путают 401 и 403, а бизнес-отказ отдают как 500. Клиент повторяет запрос, который никогда не пройдёт, а дежурные ищут несуществующую аварию.

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