8. Обработка ошибок

Правильная обработка ошибок — ключевой аспект надёжного API. tRPC предоставляет специальный класс TRPCError для генерации типизированных ошибок с HTTP-кодами и удобную систему их обработки на клиенте.

Класс TRPCError

TRPCError — это класс ошибки, специфичный для tRPC. При его выброске из процедуры клиент получает структурированный ответ с кодом ошибки, сообщением и (опционально) дополнительными данными. Используется так: throw new TRPCError({ code: 'NOT_FOUND', message: 'Пользователь не найден' }).

Коды ошибок

tRPC поддерживает набор семантических кодов ошибок, каждый из которых маппируется на HTTP-статус код. Это позволяет клиентскому коду реагировать на конкретные типы ошибок, а не на общий статус 500.

Форматирование ошибок

Через formatError можно кастомизировать формат ошибок, добавляя дополнительную информацию (например, stack trace в режиме разработки). Это настраивается при инициализации tRPC через initTRPC.create({ errorFormatter: ... }).

Обработка ошибок на клиенте

На клиенте ошибки tRPC доступны через error.data.code для получения кода ошибки, error.message для текстового описания. Библиотека React Query автоматически предоставляет error в хуках useQuery и useMutation.

Глобальная обработка ошибок

Для глобальной обработки ошибок можно использовать onError callback в настройках адаптера. Это полезно для логирования всех серверных ошибок в систему мониторинга.