4.2 KiB
HTTP API и ошибки
Источник контракта
Backend генерирует OpenAPI из собственного публичного API. Frontend использует
производное описание контракта и типизированный клиент. Изменения проходят
contract workflow.
API имеет prefix /api/v1; Swagger публикуется для локальной разработки по
environment policy, а не используется frontend в runtime.
Validation и identity
Backend преобразует и проверяет входные данные на общей HTTP-границе. Неизвестные свойства запроса удаляются; сам факт их передачи не обещает отказа. Проверка формата не заменяет бизнес-ограничения и проверку доступа к счёту. Аутентификация подтверждает личность пользователя; accountId из URL сам по себе не доказывает доступ к брокерским данным.
Error contract
Общая граница обработки HTTP-ошибок возвращает application/problem+json
со status и публичным code.
Неожиданный exception возвращает 500 / INTERNAL_SERVER_ERROR, без исходного
message/stack. Типичный ответ:
{ "status": 401, "code": "UNAUTHORIZED" }
Для input validation контракт требует 400, VALIDATION_ERROR и errors как
массив { pointer, detail }, где pointer адресует поле запроса. Это требование
не считается проверенным одним описанием OpenAPI: нужна проверка реального
HTTP-ответа после всех стадий обработки запроса.
Требует ручной проверки: согласованность деталей ошибок валидации полей
в полном HTTP-потоке пока не подтверждена. Известно расхождение формата ошибок
между стадиями валидации и формирования ответа; наличие описания в OpenAPI
не доказывает передачу ожидаемых pointer и detail.
Ответ не включает автоматически все поля RFC (type, title, instance).
Добавление обязательного поля является изменением публичного контракта.
Клиент выбирает поведение по публичному коду, а не по внутреннему тексту ошибки.
Domain errors и auth
Специальный code определяется сценарием; общее преобразование ошибок и безопасная форма ответа принадлежат HTTP-границе. Auth endpoints используют свои status и cookie operations: Authentication. T-Bank token failure и временная недоступность имеют разные значения: Connection API. Raw upstream/Prisma errors и secrets не передаются frontend.
Граница доказательства
Сравнение OpenAPI подтверждает согласованность схем, а не результат каждого запроса. Безопасная обработка неожиданной ошибки проверяется отдельно. Валидация, доступ, статусы и cookie требуют проверки полного HTTP-потока; атомарность хранения — проверки с изолированной реальной базой. Известное ограничение сквозных проверок описано в проверке backend.