Хватит писать try/catch вокруг fetch: история о том, как я устал ловить ошибки

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

Пишешь fetch и рефлекторно добавляешь try/catch. Где-то словил TypeError, где-то таймаут, где-то сервер вернул 500. В итоге половина кода превращается в кашу проверок, а другая половина — в обработчики ошибок.

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

Так появилась библиотека @asouei/safe-fetch. Ее задача проста: убрать try/catch из проектов навсегда.

Проблемы, которые достали всех

Помните эту красоту?

try {   const res = await fetch('/api/users');   if (!res.ok) {     throw new Error(`HTTP ${res.status}: ${res.statusText}`);   }   const data = await res.json();   // что-то делаем с data } catch (e) {   // а тут ловим все подряд: таймауты, 404, проблемы с сетью   console.error('Что-то пошло не так:', e.message); } 

Через месяц в проекте половина функций выглядит именно так. А проблемы одни и те же:

• fetch кидает исключения только на сетевые сбои. 404 и 500 надо ловить руками

• Нет «общего таймаута» на операцию. Только костыли с AbortController

• Логика повторов? Пиши сам или тащи тяжелый axios

• Ошибки не типизированы. В TypeScript приходится гадать что в e.message

Что я хотел получить

Три простые вещи:

1. Никаких throw
Каждый вызов возвращает результат с понятным флагом ok.

2. Нормализованные ошибки
Вместо загадочного e.message — четкие типы: NetworkError, TimeoutError, HttpError, ValidationError.

3. Фишки из коробки
Общий таймаут, умные ретраи, поддержка Retry-After.

Вот как это выглядит:

import { safeFetch } from '@asouei/safe-fetch';  const result = await safeFetch.get<{ users: User[] }>('/api/users');  if (result.ok) {   console.log(result.data.users); } else {   console.error(result.error.name); // NetworkError | TimeoutError | ... } 

Результат всегда предсказуемый: либо { ok: true, data }, либо { ok: false, error }.
Ни одного try/catch в бизнес-логике.

Что под капотом

Двойные таймауты

Можно задать timeoutMs для одной попытки и totalTimeoutMs для всей операции:

const api = createSafeFetch({   timeoutMs: 5000,        // 5с на попытку   totalTimeoutMs: 30000   // 30с всего (включая ретраи) }); 

Умные ретраи

По умолчанию повторяются только GET и HEAD — это защищает от случайных дубликатов POST-запросов:

const result = await safeFetch.get('/api/flaky', {   retries: {     retries: 3,     baseDelayMs: 300  // экспоненциальный backoff   } }); 

Поддержка Retry-After

Если сервер вернул 429 с заголовком — библиотека сама подождет:

// Сервер: 429 Too Many Requests, Retry-After: 60 // safe-fetch: ждем ровно 60 секунд 

Validation без исключений

Можно подключить Zod или другую схему:

const result = await safeFetch.get('/user/123', {   validate: (data) => UserSchema.safeParse(data).success      ? { success: true, data }      : { success: false, error: 'Invalid user' } }); 

Реальная польза

До: кодовая база из ада

async function getUsers() {   try {     const res = await fetch('/api/users');     if (!res.ok) throw new Error(`${res.status}`);     return await res.json();   } catch (e) {     logger.error('Users fetch failed', e);     throw e; // пробрасываем дальше   } }  async function createUser(data) {   try {     const res = await fetch('/api/users', {       method: 'POST',       body: JSON.stringify(data)     });     if (!res.ok) throw new Error(`${res.status}`);     return await res.json();   } catch (e) {     logger.error('User creation failed', e);     throw e;   } } 

После: чистый код

const api = createSafeFetch({   baseURL: '/api',   interceptors: {     onError: (error) => logger.error('API error', error)   } });  async function getUsers() {   return api.get<User[]>('/users'); }  async function createUser(data: NewUser) {   return api.post<User>('/users', data); } 

Весь error handling в одном месте. Никаких дублирующихся проверок.

История из практики

У меня был проект в небольшой команде, где мы работали с несколькими сторонними API. На бумаге всё выглядело просто: дергаем данные, отображаем в интерфейсе. Но реальность быстро всё усложнила.

Что пошло не так:

• Один сервис периодически отвечал 500-ми ошибками

• Другой любил возвращать пустые JSON-ы, хотя статус был 200

• Иногда ответы зависали на десятки секунд, и пользователи жаловались, что «кнопка не работает»

В итоге код превратился в хаос из try/catch, таймеров с AbortController и кучи логов вроде «Request failed again». Мы даже обсуждали идею тащить axios, хотя никто не горел желанием добавлять ещё одну тяжелую зависимость.

В какой-то момент я собрался и сказал: «Хватит. Мы тратим больше времени на ловлю ошибок, чем на фичи». Так появился safe-fetch.

После перехода:

• Весь error handling уехал в interceptors — стало понятно, где искать баги

• Ретраи на GET реально спасли от флейки API (раньше мы просто рефрешили страницу)

• Общий таймаут избавил от «вечных» спиннеров, когда пользователь ждал ответа, который никогда не придёт

• В логах наконец появились внятные названия ошибок (NetworkError, TimeoutError), а не загадочные «undefined»

Через пару недель мы заметили, что больше вообще не пишем try/catch вокруг запросов. И это стало огромным облегчением для всей команды.

Сравнение с конкурентами

Установка и первые шаги

npm install @asouei/safe-fetch 

Базовый пример:

import { safeFetch } from '@asouei/safe-fetch';  const users = await safeFetch.get<User[]>('/api/users'); if (users.ok) {   console.log(users.data); } else {   console.error(users.error.name, users.error.message); } 

Для больших проектов:

import { createSafeFetch } from '@asouei/safe-fetch';  const api = createSafeFetch({   baseURL: 'https://api.example.com',   headers: { 'Authorization': `Bearer ${token}` },   timeoutMs: 10000,   retries: { retries: 2 } }); 

Для кого это

• Команды, уставшие от непредсказуемых ошибок и дублирующего кода

• Проекты с жесткими SLA, где важны таймауты и ретраи

• TypeScript-кодбазы, где нужна точная типизация ошибок

• Разработчики, которые хотят простоту fetch с production-готовностью

Что дальше

Библиотека уже готова к продакшену. В планах:

• ESLint правила для паттерна { ok }

• Готовые адаптеры для React Query и SWR

• Примеры для Next.js и Cloudflare Workers

Заключение

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

safe-fetch не пытается заменить axios или ky. Она решает одну задачу: делает fetch безопасным и предсказуемым. Никаких революций — просто убирает ту ежедневную боль, с которой мы все смирились.

Может, вы тоже устали объяснять джунам, почему нужно проверять res.ok? Или писать одинаковые обработчики ошибок в каждом API-методе? Если да — попробуйте. Возможно, через неделю вы уже не захотите возвращаться к старым паттернам.

А если найдете баги или захотите что-то улучшить — буду рад увидеть в Issues. В конце концов, эта библиотека родилась из реальных проблем, и лучше всего она растет от реального фидбека.

• 🌟 Библиотека добавлена в Awesome TypeScript — один из крупнейших мировых списков лучших TypeScript-проектов

---

Попробовать самому:

• GitHub репозиторий

• Документация и примеры

• npm пакет

P.S. Если статья была полезна — звезда в репозитории и ваш фидбек в Issues помогут двигать проект дальше.