Гайды

Как обрабатывать ошибки API — retry, backoff и когда повтор делает хуже

Иллюстрация: письма, которые возвращаются и уходят снова с паузой

Чужой сервис моргнул на восемь секунд. Твой код честно повторил запрос. И ещё раз. И ещё.

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

Это называется retry storm, и устраивает его обычно самый заботливый код. Разберём по шагам, как повторять правильно.

Шаг 1. Раздели ошибки на два ведра

Первое и главное: половину ошибок повторять бессмысленно. Они не «пройдут», сколько ни жди.

Ориентир — код ответа:

| Код | Что значит | Повторять? | |---|---|---| | 400, 422 | запрос кривой | нет, чини запрос | | 401, 403 | не пустили | нет, чини ключ или права | | 404 | нет такого | нет | | 408 | таймаут запроса | да | | 429 | слишком часто | да, но особым образом | | 500, 502, 503, 504 | у них проблемы | да | | сеть отвалилась | связи нет | да |

Правило на пальцах: «это я виноват» — не повторяем, «это они прилегли» — повторяем.

Ретрай на 400 — это бесконечный цикл, который никогда не выйдет. Ретрай на 401 — вернейший способ, чтобы сервис заблокировал твой ключ за подозрительную активность.

Шаг 2. Никогда не повторяй сразу

Второй запрос через десять миллисекунд после первого прилетит ровно в тот же перегруженный сервер. Пауза должна расти — это экспоненциальная задержка (exponential backoff):

пауза = min(потолок, база × 2^номер_попытки)

С базой 300 мс получается 300 мс → 600 → 1200 → 2400. Потолок обязателен, иначе шестая попытка уйдёт ждать минуту.

const delay = Math.min(10_000, 300 * 2 ** attempt);

Шаг 3. Добавь дрожание — иначе синхронный залп

Тонкость, которую пропускают почти все.

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

Лечится случайностью — jitter. Самый простой и рабочий вариант («full jitter» из классического разбора AWS): взять случайное число от нуля до посчитанной паузы.

const backoff = Math.min(10_000, 300 * 2 ** attempt);
const wait = Math.random() * backoff;   // ← вот эта строка и есть весь трюк

Одна строка превращает толпу у двери в спокойную очередь.

Шаг 4. Если сервер сказал, сколько ждать — слушайся

При превышении лимита запросов (код 429) сервис часто присылает заголовок Retry-After — сколько секунд ждать.

Это не рекомендация, а прямой ответ на твой вопрос «когда можно?». Своя формула тут проигрывает всегда: сервер знает, когда у него откроется окно, а ты гадаешь.

const after = res.headers.get("Retry-After");
const wait = after ? Number(after) * 1000 : backoffWithJitter(attempt);

Шаг 5. Убедись, что повтор безопасен

Самый неприятный сценарий: запрос дошёл и выполнился, а ответ потерялся по дороге. Со стороны твоего кода это выглядит как обычный таймаут. Он повторяет — и списывает деньги второй раз.

Поэтому перед ретраем спроси: что будет, если операция выполнится дважды?

  • Чтение (получить список, открыть запись) — повторяй спокойно.
  • Замена целиком и удаление — обычно тоже: результат тот же.
  • Создание чего-либо (заказ, платёж, отправка письма) — опасно.

Для опасных случаев есть готовое решение: ключ идемпотентности. Ты сам генерируешь уникальную строку на операцию и шлёшь её заголовком; сервер запоминает и на повтор с тем же ключом отвечает старым результатом, а не выполняет заново. Так устроены все нормальные платёжные API — загляни в их доки, скорее всего, оно там уже есть.

Что получится

Собранная логика, к которой сводятся все пять шагов:

async function callApi(url, options = {}, attempt = 0) {
  const res = await fetch(url, options);
  if (res.ok) return res.json();

  const retryable = [408, 429, 500, 502, 503, 504].includes(res.status);
  if (!retryable || attempt >= 4) throw new Error(`API ${res.status}`);

  const after = res.headers.get("Retry-After");
  const wait = after
    ? Number(after) * 1000
    : Math.random() * Math.min(10_000, 300 * 2 ** attempt);

  await new Promise((r) => setTimeout(r, wait));
  return callApi(url, options, attempt + 1);
}

Четыре попытки, растущая пауза со случайностью, уважение к Retry-After, безнадёжные коды — сразу наверх. Дальше остаётся только логировать неудачу так, чтобы её было видно, а не молча возвращать пустой массив.

Сколько попыток делать?

Три-четыре и хватит. Если сервис не ответил за четыре растущие паузы, он не «моргнул», а лежит — и дальше ты просто добавляешь ему нагрузки. Лучше честно упасть и показать пользователю понятное сообщение.

Почему код от ИИ обычно без ретраев?

Потому что ты просишь «сделай запрос к API», а не «сделай устойчивый запрос». Модель пишет счастливый путь — он короче и выглядит чище. Ретраи, таймауты и обработку 429 приходится запрашивать отдельно и явно.

Нужен ли ретрай, если API мой собственный?

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

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →