Ошибки: SkipRetry и Fatal

Asynq SkipRetry — сентинелл-ошибка, которую хендлер возвращает вместо обычной: очередь не станет назначать ретрай и сразу отправит задачу в архив. Возврат простой: return asynq.SkipRetry, если нечего добавить к делу, или fmt.Errorf("json.Unmarshal failed: %v: %w", err, asynq.SkipRetry), если к сентинеллу хочется приклеить контекст — обёртка через %w работает, и errors.Is находит SkipRetry внутри цепочки. Механика внутри библиотеки честная: фильтр после хендлера проверяет ошибки через errors.Is, поэтому любые ваши обёртки и Join-ы не помешают распознаванию. Два момента, о которых часто спотыкаются. Первый: SkipRetry — это всё-таки ошибка, а не успех; задача считается упавшей, ErrorHandler получит её, счётчик Failed очереди вырастет — «не повторять» не значит «всё хорошо». Второй: архив — не мусорка; задача в нём сохранена для осмотра, и её можно запустить вручную, когда причину починят. Порядок действий при фатальной ошибке поэтому такой: пометить SkipRetry, увидеть задачу в архиве, починить данные, запустить вручную — полный цикл вместо двадцати суток ретраев.

Ошибки задач go раскладываются по одному вопросу: изменит ли повтор исход. Ретраибельны всё, что про «сейчас не работает»: недоступная сеть и таймауты, пятьсот-коды, блокировки базы, исчерпанные квоты с окном ожидания. Фатальны всё, что про «так не бывает»: битый payload и неожиданный формат, отсутствие записи, которую никто не заведёт, нарушение инварианта, отказ в доступе по правам. Проверка перед возвратом ошибки простая: «представьте, что через пять минут всё здорово — изменится ли результат?» Если нет — это SkipRetry, а не ретрай. На границе живут случаи, где ответ зависит от контекста: отсутствие записи в базе для вебхука «заказ создан» — фатально, если заказ и правда не придёт, и ретраибельно, если вы читаете реплику с отставанием; денежная операция с неясным исходом — не ошибка вовсе, а повод для проверки состояния, о чём говорит восемнадцатый урок об идемпотентности. Ещё две пограничные категории стоит проговорить отдельно. Работа уже сделана — «письмо отправлено» по повторному вебхуку: повтор не нужен, но и архив не нужен, потому что ничего не сломалось; это территория RevokeTask из конца урока. Деградация, которая сама пройдёт, — плавающий лимит соединений, переполненный диск: здесь ретрай прав, но паузу должна диктовать ваша RetryDelayFunc из тринадцатого урока, а не слепая экспонента. Грубая ошибка противоположного сорта — оборачивать в SkipRetry всё подряд: тогда настоящий сбой сети уйдёт в архив с первой же неудачи, и очередь молча перестанет выполнять свою главную работу.

В реальном проекте хендлеры обёртывают сервисный слой, и решение «фатально или нет» хочется принимать в одном месте, а не в каждом return. Идиома — свой тип ошибки с классификацией внутри: type AppError struct{ Err error; Permanent bool } с методом Error и, если нужно, Unwrap. Сервисный слой помечает Permanent там, где знает это лучше всех: валидация, отсутствие записи, отказ в доступе. Хендлер заканчивается одной точкой сборки: если errors.As находит AppError с Permanent — вернуть обёртку со SkipRetry, иначе вернуть ошибку как есть. Так знание о повторах не расползается: сервис не знает про asynq, asynq не знает про ваш бизнес, а мост между ними — десять строк адаптера. Внедряйте постепенно: один адаптер в самом шумном хендлере, затем метрики по классам из ErrorHandler, затем общий пакет ошибок для всех воркеров — миграция без большого переписывания. Тот же адаптер — удобное место для декора контекста: добавить идентификатор задачи из GetTaskID, счётчик попытки из GetRetryCount, чтобы текст ошибки в архиве был самодостаточным для разбора. Имена и форму подбирайте под проект: где-то хватит булева поля, где-то — enum из трёх классов «сеть, данные, бизнес». Важно только одно: классификация живёт в типе, а не в разборе строк текста ошибки — строковые проверки ломаются от первой же правки формулировки.

Архив — конечная станция неудачных задач: туда же, куда SkipRetry отправляет задачу сразу, очередь кладёт задачи с исчерпанными попытками из шестого урока. Задача в архиве сохранена целиком — тип, payload, текст последней ошибки, счётчик попыток — и живёт там с ограничениями, о которых стоит знать: библиотека держит не больше десяти тысяч задач в архиве каждой очереди и удаляет записи старше девяноста дней, старое вытесняется новым. Обрезка выполняется прямо при каждой записи в архив, внутри той же операции: отдельного фонового чистильщика для архива нет, и на пустой очереди он не нужен. Отсюда следствие для расследований: записи старше девяноста дней вы не увидите никогда, и если инцидент требует глубокого взгляда назад, выгружайте архив в собственное хранилище периодической задачей. Практический вывод: архив — рабочий инструмент разбора, но не вечное хранилище; если фатальная ошибка массовая, десять тысяч строк переполнятся быстро, и часть улик уйдёт. Смотреть на архив можно двумя способами: глазами — вкладка Archived в asynqmon из шестнадцатого урока, и кодом — Inspector с ListArchivedTasks и RunTask из пятнадцатого, что позволяет починить данные и вернуть задачу в работу из вашего же админ-хендлера. Текст ошибки в архиве — то, ради чего стоит обёртывать SkipRetry с контекстом: «empty event_id» на входе говорит всё, а «skip retry for the task» — ничего, кроме того, что сентинелл дошёл до места.

У SkipRetry есть младший брат — RevokeTask, появившийся в версии 0.25.0: задача не ретраится и в архив не попадает, а помечается выполненной и исчезает из активных. Сценарий у него один, но важный: задача, чья неудача — нормальный исход, который не стоит ни двадцати пяти попыток, ни строки в архиве. Классика — дубликаты: хендлер обнаруживает, что такой вебхук уже обработан, и вместо архивной строки «duplicate» просто возвращает RevokeTask. Второй случай — самоочистка: задача-«пиналочка» для внешнего процесса, который к моменту запуска уже не нужен. Обратная сторона — беззвучность: задача исчезает, и без своего лога вы никогда не узнаете, что она вообще была; поэтому RevokeTask идёт в паре с логом в хендлере, который фиксирует решение. Для всего остального выбирайте SkipRetry: архив с текстом ошибки дешевле, чем исчезнувшая задача, и разбирать инцидент по архиву можно и месяц спустя. Разница между двумя сентинеллами запоминается одной фразой: SkipRetry — «сохрани для осмотра», RevokeTask — «отмени тихо».