Как обрабатывать ошибки 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 коротких урока на телефоне.





