Повторні спроби та недоставлені повідомлення

Railhook повторює доставку за сталим розкладом повторних спроб, доки ендпоінт не відповість 2xx або спроби не вичерпаються. Те, що він полишив, потрапляє в «Недоставлені повідомлення».

Статуси доставки

Статус	Значення
`PENDING`	Щойно створена або чекає на наступну спробу.
`PROCESSING`	Воркер захопив її на одну спробу. Якщо воркер падає, доставку знову забирає інший воркер, щойно мине час захоплення (`WEBHOOK_CLAIM_TIMEOUT_SECONDS`, типово 300).
`SUCCESS`	Ендпоінт відповів `2xx`. Більше нічого не надсилається.
`FAILED`	Railhook припинив спроби, бо жодна наступна спроба не допоможе: URL відхилено або ендпоінт не може прийняти доставку.
`DLQ`	Спроби вичерпано, ендпоінт відповів статусом, якого наступна спроба не змінить, або доставка перевищила максимальний час життя. У панелі це «Недоставлені повідомлення».

Коли буде ще одна спроба

Результат спроби	Що відбувається
`2xx`	`SUCCESS`.
`408`, `429`, будь-який `5xx`	Повторна спроба за розкладом. Це типовий набір. Підписка або вхідне призначення можуть його змінити: див. Які статуси варті повтору.
Помилка з’єднання, тайм-аут або хост, який не вдалося знайти в DNS	Повторна спроба за розкладом.
Трансформацію не вдалося застосувати	Повторна спроба за розкладом. Оригінальний вміст замість трансформованого ніколи не надсилається.
Будь-який інший `4xx` або `3xx`	`DLQ` одразу після першої спроби, без решти розкладу. Виправте облікові дані чи URL, а потім повторіть доставку з «Недоставлених повідомлень». Переспрямувань Railhook не виконує.
Ендпоінт не може прийняти доставку, наприклад, він не перевірений або його URL не пройшов перевірку приватних адрес	`FAILED` без жодної спроби.

Розклади повторних спроб

Кожен інтервал отримує випадковий розкид від 50% до 150% свого значення, щоб повторні спроби не приходили хвилею.

Напрямок	Спроб	Інтервали між спробами	Номінально загалом
Вихідний (доставка)	7	1 хв, 5 хв, 15 хв, 1 год, 6 год, 24 год	близько 31 год 21 хв
Вхідний (пересилання)	5	1 хв, 5 хв, 15 хв, 1 год	близько 1 год 21 хв

Підписка або вхідне призначення можуть задати власні maxAttempts (від 1 до 20) і retryDelays у секундах. Якщо спроб більше, ніж інтервалів, останній інтервал повторюється.

Що не є спробою

Ліміт запитів організації чи ендпоінта, зайняті слоти паралельності, розімкнений circuit breaker або впорядкована доставка, що чекає на попередню, зупиняють запит ще до надсилання. Це відкладення: воно не витрачає спробу й не просуває розклад, доставку просто планують знову.

Тайм-аути

Одна спроба чекає на відповідь 30 секунд, якщо в підписці не задано timeoutSeconds (від 1 до 60). Тайм-аут є невдалою спробою.

Які статуси варті повтору

Типово доставку повторюють на 408, 429 і будь-якому 5xx, і більше ні на чому. Підписка або вхідне призначення можуть змінити це через retryableStatuses, список термів через кому:

Терм	Відповідає
`429`	Саме цьому статусу.
`500-599`	Діапазону, включно з обома межами.
`5xx`	Скорочення для `500-599`. Так само `4xx`, `3xx`, `2xx`, `1xx`.
`>=500`, `>500`, `<=408`, `<400`	Відкритому з одного боку діапазону.
`!501`	Виключенню. Будь-який терм можна почати з `!`.

Виключення мають перевагу, хоч би де їх написали: 5xx,!501 і !501,5xx означають те саме.

408,429,500-599    типовий
5xx,!501           повторювати всі помилки сервера, крім «не реалізовано»
>=500,408,429,409  отримувач, який відповідає 409, поки ще наздоганяє
408,429            отримувач, чий 5xx означає остаточну відмову від вмісту

API відхиляє список, який не може прочитати, і називає помилковий терм. Статус, якого немає в списку, обробляється як 4xx: доставка потрапляє в «Недоставлені повідомлення» після першої спроби.

Retry-After

Отримувач, який відповідає 429 або 503, може задати Retry-After. Railhook приймає обидві форми HTTP: секунди або дату HTTP. Три обмеження:

Лише на 429 і 503. Лише тут він означає «перевантажений, зачекай». На 500 це часто заголовок, який залишив проксі.
Він може лише відсунути спробу далі. Отримувач не може змусити Railhook повторювати частіше, ніж налаштував власник підписки.
Він обмежений зверху змінною WEBHOOK_RETRY_AFTER_MAX_SECONDS (типово 21600, шість годин). Інакше одна неправильно налаштована відповідь могла б відкласти доставку на рік.

Шість годин є найбільшим інтервалом, спільним для обох типових розкладів, і сім спроб по максимуму вкладаються в 96-годинний максимальний час життя. Довше очікування (Hookdeck дозволяє сім днів) однаково обрізав би цей ліміт. Поставте 0, щоб ігнорувати заголовок.

Прийнятий Retry-After не додає спроби. 429 на останній спробі потрапляє в «Недоставлені повідомлення», як і будь-яка інша невдача.

Максимальний час життя доставки

Якщо доставку не вдалося завершити за 96 годин від створення, вона потрапляє в «Недоставлені повідомлення», скільки б спроб не було. Для доставки, повтореної або повторно надісланої вручну, час рахується від цього моменту, тож вона отримує свої нові спроби. Для вхідних пересилань обмеження 24 години. Обмеження підхоплює доставки, що застрягли; ті, що щоразу падають, зупиняє розклад.

Змінна	Типово	Напрямок
`DELIVERY_ESCALATION_HARD_CAP_HOURS`	`96`	Вихідний
`FORWARD_ESCALATION_HARD_CAP_HOURS`	`24`	Вхідний

Воркер не запуститься, якщо типовий розклад із максимальним розкидом не вміщується в цей час.

Недоставлені повідомлення

«Недоставлені повідомлення» показують кожну полишену доставку з ендпоінтом, типом події, кількістю спроб і останньою помилкою. API: GET /api/v1/projects/{projectId}/dlq.

Повторна спроба з «Недоставлених повідомлень» повертає ту саму доставку в PENDING і дає їй ще 3 спроби. Доставка зберігає ідентифікатор, історію спроб і Idempotency-Key, тож отримувач, який її вже обробив, розпізнає дублікат. Перша нова спроба йде одразу. Повторити одну доставку можна через POST /api/v1/projects/{projectId}/dlq/{deliveryId}/retry, кілька через POST /api/v1/projects/{projectId}/dlq/retry.

Для вхідних вебхуків такий самий екран називається «Недоставлені пересилання». Повторна спроба створює нове пересилання на те саме призначення, що починає зі спроби 1.