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

Кожна помилка 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`	Що робити
`400`	`validation_error`	Виправте поля, названі в `fieldErrors`.
`400`	`malformed_request`	Тіла немає або воно не є коректним JSON.
`400`	`missing_parameter`, `invalid_parameter`	Параметра запиту чи шляху бракує або він у хибному форматі.
`400`	`invalid_url`	URL відхилено, наприклад захистом від SSRF.
`400`	`invalid_request`	Запит зрозуміли, але відхилили, наприклад подію, що розгалузилася б понад ліміт. Прочитайте `message`.
`401`	`unauthorized`	Облікові дані відсутні, сплили або хибні. Оновіть токен доступу або перевірте заголовок `X-API-Key`.
`403`	`forbidden`	Автентифіковано, але роль чи область дії ключа цього не дозволяє. Ключ `READ_ONLY` не може писати.
`404`	`not_found`	Нічого з таким ідентифікатором у вашій організації немає.
`405`	`method_not_allowed`	Хибний HTTP-метод. Заголовок `Allow` перелічує правильні.
`409`	`conflict`	Уже існує або змінилося, поки ви редагували. Перечитайте й спробуйте знову.
`413`	`payload_too_large`	Тіло перевищує ліміт розміру.
`415`	`unsupported_media_type`	Надсилайте `Content-Type: application/json`.
`422`	`unprocessable_entity`	Запит коректний, але його не можна застосувати в поточному стані ресурсу.
`429`	`rate_limit_exceeded`, `organization_rate_limit`, `platform_rate_limit`	Зачекайте `Retry-After` секунд і повторіть.
`500`	`internal_error`	Збій на боці Railhook. Повторіть із витримкою.

Деякі помилки несуть лише загальний код — client_error для 4xx або server_error для 5xx — у тому самому конверті: наприклад, ліміт частоти входу чи заблокована зміна останнього власника. Спершу розгалужуйтесь за status, а error використовуйте для уточнення.

Ліміти частоти

Ліміт	Стосується	За замовчуванням	При 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`)	`429`

Кожна відповідь POST /api/v1/events несе поточний бюджет проєкту:

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

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

Ліміт	За замовчуванням	Змінна
Тіло запиту, 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 без подробиць, тож провайдер нічого не дізнається про ваш план.

Що далі

Довідник APIКоди статусів для кожного запиту.

АвтентифікаціяЯк виправити 401 чи 403.

Повтори та невдалі повідомленняЯк Railhook повторює доставку на ваші ендпоінти.