Помилки та ліміти

Усі помилки API Railhook мають однакову структуру, тож одного обробника у вашому клієнті вистачить для всіх.

Формат помилки

{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "status": 400,
  "fieldErrors": {
    "type": "Event type is required",
    "data": "Event data cannot be empty"
  }
}

Поле	Завжди є	Що означає
`error`	Так	Незмінний машиночитний код. Саме за ним розрізняйте помилки в коді.
`message`	Так	Пояснення для людини. Не розбирайте його програмно.
`status`	Так	HTTP-статус, продубльований у тілі
`fieldErrors`	Ні	У помилках валідації: назва поля → що з ним не так

Коди помилок

Статус	`error`	Що робити
`202`	`authorization_pending`	Лише для `railhook login`: код ще не підтверджено в браузері. Опитайте ще раз.
`400`	`validation_error`	Виправте поля, перелічені в `fieldErrors`.
`400`	`malformed_request`	Тіла немає або воно не є коректним JSON.
`400`	`missing_parameter`, `invalid_parameter`	Параметра запиту чи шляху немає або він має неправильний формат.
`400`	`invalid_url`	URL відхилено, наприклад, захистом від SSRF.
`400`	`invalid_request`	Запит зрозуміло, але відхилено, наприклад, подію, яка розгалузилася б понад ліміт, чи прострочене посилання для підтвердження. Прочитайте `message`.
`400`	`captcha_failed`	Перевірку на публічній формі не пройдено. Пройдіть її ще раз.
`401`	`unauthorized`	Облікових даних немає, вони прострочені або неправильні. Оновіть токен доступу або перевірте заголовок `X-API-Key`.
`401`	`signature_verification_failed`	Лише для ingress-адреси: підпис провайдера не збігся із секретом джерела.
`402`	`quota_exceeded`	Досягнуто ліміту тарифу. У `fieldErrors` вказано квоту, використання, ліміт і тариф.
`403`	`forbidden`	Автентифікацію пройдено, але роль чи рівень доступу ключа цього не дозволяє. Ключ `READ_ONLY` не може нічого змінювати.
`403`	`demo_read_only`	У живому демо нічого не можна змінити. Створіть обліковий запис.
`403`	`reauthentication_required`	Лише для панелі адміністратора платформи: останній вхід був надто давно. Увійдіть знову.
`403`	`suspended`, `tunnel_suspended`	Ingress-адреса чи адреса тунелю призупиненої організації. Вона нічого не приймає, доки призупинення не знято.
`404`	`not_found`	У вашій організації немає нічого з таким ідентифікатором.
`405`	`method_not_allowed`	Неправильний HTTP-метод. Правильні перелічено в заголовку `Allow`.
`409`	`conflict`	Таке вже існує або змінилося, поки ви редагували. Отримайте актуальну версію й спробуйте ще раз.
`410`	`gone`	Це існувало, але більше не придатне: прострочений чи вже використаний код пристрою або запрошення, закритий тунель. Почніть заново.
`410`	`disabled`	Лише для ingress-адреси: джерело вимкнено.
`413`	`payload_too_large`	Тіло перевищує ліміт розміру.
`415`	`unsupported_media_type`	Надсилайте `Content-Type: application/json`.
`423`	`account_locked`	Забагато невдалих спроб входу. Зачекайте стільки хвилин, скільки вказано в `message`, або скиньте пароль.
`429`	`rate_limit_exceeded`, `organization_rate_limit`, `platform_rate_limit`, `portal_rate_limit`, `rate_limited`	Зачекайте стільки секунд, скільки вказано в `Retry-After`, якщо його надіслано, і повторіть запит. `rate_limited` — це ліміт панелі адміністратора платформи.
`429`	`too_many_active_urls`, `contact_busy`	Публічний тестер вебхуків і форма зв’язку: з цієї адреси вже створено забагато активних тестових URL, або форма сьогодні прийняла стільки повідомлень, скільки може.
`500`	`internal_error`	Збій на боці Railhook. Повторіть запит з експоненційною затримкою.
`502`	`tunnel_error`	Лише для адреси тунелю: CLI не зміг достукатися до вашого локального застосунку. Причину вказано в `message`.
`503`	`service_unavailable`	Ще не готово, наприклад, дані демо ще готуються. Повторіть за хвилину.
`503`	`tunnel_offline`	Лише для адреси тунелю: до цього тунелю не під’єднано жодного CLI.
`503`	`tester_busy`, `contact_unavailable`	Публічний тестер вебхуків заповнено, або в цьому розгортанні немає адреси підтримки.
`504`	`tunnel_timeout`	Лише для адреси тунелю: локальний застосунок не відповів вчасно або CLI від’єднався.
`4xx`	`client_error`	Відмова без окремого коду, наприклад, ендпоінти MCP OAuth у розгортанні, де їх вимкнено. Прочитайте `status` і `message`.
`5xx`	`server_error`	Помилка сервера без окремого коду. Повторіть запит з експоненційною затримкою.

client_error і server_error — запасні коди для тих небагатьох помилок, що не мають власного. Тож спершу перевіряйте status, а error використовуйте для уточнення. Ендпоінти MCP OAuth під /oauth/ натомість відповідають у форматі, якого очікують клієнти OAuth: error і error_description з кодами OAuth, наприклад, invalid_grant.

Ліміти частоти запитів

Це типові значення для розгортання на власному сервері. У Railhook Cloud свої ліміти, описані нижче.

Ліміт	Що обмежує	Типово	Відповідь 429
Приймання подій	`POST /api/v1/events`, для кожного проєкту	100 на секунду	`rate_limit_exceeded` із заголовками залишку ліміту
Організація	Увесь API-трафік однієї організації	Вимкнено (`ORG_RATE_LIMIT_ENABLED=false`); 200 на секунду, якщо ввімкнено	`organization_rate_limit`, `Retry-After: 1`
Платформа	Увесь трафік, для кожного інстансу API	5000 на секунду (`GLOBAL_RATE_LIMIT_PER_SECOND`)	`platform_rate_limit`
Ingress-адреса	Вебхуки, отримані на `/ingress/…`, для кожного джерела	100 на секунду (`WEBHOOK_INCOMING_RATE_LIMIT_PER_SECOND`), якщо джерело не задає власного ліміту	`Retry-After: 1`
Вхід	Для кожної IP-адреси і кожного email	10 на хвилину (`AUTH_RATE_LIMIT_LOGIN_PER_MINUTE`)	`rate_limit_exceeded`
Оновлення сесії	Для кожного токена оновлення і кожної IP-адреси	30 на хвилину на токен (`AUTH_RATE_LIMIT_REFRESH_PER_TOKEN_PER_MINUTE`), 600 на хвилину на IP-адресу (`AUTH_RATE_LIMIT_REFRESH_PER_IP_PER_MINUTE`)	`rate_limit_exceeded`

Кожна відповідь на POST /api/v1/events містить поточний залишок ліміту проєкту:

Заголовок	Що означає
`X-RateLimit-Limit`	Скільки запитів дозволено в поточному вікні
`X-RateLimit-Remaining`	Скільки з них лишилося
`X-RateLimit-Reset`	Unix-час, коли почнеться нове вікно
`Retry-After`	Лише у відповіді `429`: скільки секунд чекати

Ліміти Railhook Cloud

У Railhook Cloud на railhook.io кожна організація працює на тарифі Free. Доступні всі функції, зокрема воркфлоу, правила, відтворення і mTLS; обмежено лише обсяги. Ці ліміти діють замість наведених вище типових значень для власного сервера:

Ліміт	Тариф Free
Приймання подій (`POST /api/v1/events`)	10 на секунду для кожного проєкту
Події	10 000 на місяць
Проєкти	3
Ендпоінти	5 на проєкт
Учасники	5 на організацію
Зберігання подій	7 днів
Активні тунелі	1
Доставок на подію (розгалуження)	100

На власному сервері тарифних лімітів немає. Діють лише типові значення з таблиць на цій сторінці.

Ліміти розміру та розгалуження

Ліміт	Типово	Змінна
Тіло запиту до API	256 КБ (262144 байти)	`WEBHOOK_MAX_PAYLOAD_SIZE_BYTES`
Тіло запиту на ingress-адресу	512 КБ (524288 байтів)	`WEBHOOK_INCOMING_MAX_PAYLOAD_SIZE_BYTES`
Доставок на подію (розгалуження)	50 на власному сервері	—

Для ingress-адреси ліміт вищий, бо розмір того, що надсилає провайдер, від вас не залежить. Подію, яка збігається з більшою кількістю підписок, ніж дозволяє ліміт розгалуження, відхиляють повністю з 400. Не буває так, щоб її доставили на частину відповідних ендпоінтів, а на решту ні.

Відповіді ingress-адреси

Ingress-адреса відповідає не вам, а провайдеру, який надіслав вебхук, тому її відповіді коротші: успішне отримання — це 202 із status і requestId, а помилка містить error і message без status. Коли в розгортанні з тарифами вичерпано квоту, ingress-адреса відповідає 429 з Retry-After: 3600 і без подробиць, тож провайдер нічого не дізнається про ваш тариф.