Помилка «невірне посилання» в API: перевірка URL перед створенням замовлення

Що означає помилка «невірне посилання» в API

Помилка «невірне посилання» означає, що API не змогло прийняти URL у полі цілі замовлення. Це не завжди друкарська помилка в адресі. Сервіс може відхилити посилання через невідповідний формат, тип сторінки, редирект, обмеження доступу, кодування або невідповідність майданчика послузі.

Перевірка зазвичай відбувається до створення замовлення. API отримує URL, визначає домен і шлях, намагається розпізнати об'єкт: канал, ролик, трансляцію, публікацію або профіль. Якщо один з етапів не проходить, замовлення не буде створено. Загальний текст помилки сам по собі не показує причину — потрібно дивитися URL, параметри послуги та повну відповідь API.

Зіставте текст помилки з відповіддю API

У різних API формулювання та структура відповіді відрізняються. Іноді сервіс повертає лише повідомлення, іноді додає код, назву поля або ідентифікатор запиту. Повна відповідь корисніша за статус HTTP: навіть при успішній доставці запиту API може відхилити саме замовлення на рівні бізнес-перевірки.

Наприклад, типова відповідь може виглядати так: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Тут варто перевірити саме значення поля link. Варіант {"error":"target_not_supported"} частіше вказує не на зламану адресу, а на непідтримуваний тип об'єкта. Назви полів і кодів залежать від конкретної документації.

Зберігайте статус відповіді, тіло відповіді, ідентифікатор послуги та request_id, якщо API його повертає. Не додавайте в тікет токен доступу, cookie, підписи запиту та приватні параметри посилання.

Перевірте формат URL і значення поля запиту

Робоче в браузері посилання може не пройти машинну перевірку. У поле іноді потрапляє лише ідентифікатор ролика, нікнейм без домену, текст із повідомлення або скорочена адреса. Помилка виникає й тоді, коли URL передано не рядком, а вкладеним об'єктом або масивом.

• Передавайте повний публічний URL разом із протоколом https://.
• Перевірте домен: він має належати до майданчика обраної послуги.
• Видаліть пробіли по краях, перенесення рядка, емодзі та текст після посилання.
• Звірте ім'я поля з документацією API: link, url, target або інше.
• Переконайтеся, що в запиті передається рядкове значення, а не об'єкт з URL усередині.

Ручна вставка адреси зручна, але має недолік: у рядок легко потрапляє невидимий символ або фрагмент підпису до публікації. Перед відправкою очищайте значення, але не змінюйте сам шлях і параметри без необхідності.

Розгорніть короткі посилання та приберіть зайві редиректи

Скорочені адреси та посилання з кнопки «Поділитися» часто проходять через один або кілька редиректів. Браузер відкриває їх автоматично, а API сервісу просування може не переходити за перенаправленнями, блокувати їх або отримувати проміжну сторінку авторизації.

Для замовлення краще використовувати канонічну адресу: ту, яка видна в адресному рядку після повного завантаження потрібної сторінки. Мітки кампаній і параметри часу перегляду не завжди заважають, але параметри можуть призвести до іншого подання сторінки або вплинути на розпізнавання об'єкта.

У канонічного URL є недолік: його іноді доводиться отримувати окремо, особливо після копіювання посилання з мобільного застосунку. Зате таку адресу простіше перевірити вручну та зіставити з правилами послуги.

Виберіть посилання на об'єкт, який приймає послуга

Послуга може приймати лише один тип цілі. Замовлення для каналу не прийме посилання на запис ефіру, а послуга для переглядів ролика не прийме профіль автора. Зовні обидва URL коректні, але API зіставляє структуру адреси з призначенням послуги та відхиляє невідповідний об'єкт.

Перевірте довідник послуг: майданчик, категорію, допустимий target_type та обмеження. Якщо API вимагає окремий параметр типу цілі, він має збігатися з URL. Не замінюйте адресу контенту посиланням на пошук, хештег, добірку, головну сторінку або кабінет автора.

• Для просування каналу передавайте сторінку каналу.
• Для переглядів використовуйте посилання на конкретне відео або запис.
• Для активного ефіру передавайте URL трансляції, якщо послуга підтримує live-формат.
• Для реакцій та інших дій з публікацією використовуйте пряме посилання на публікацію.

Перевірте приватність, вікові фільтри та вимогу входу

API перевіряє не лише форму URL, а й доступність цілі. Контент може відкриватися у власника каналу, бо його браузер авторизований, але бути недоступним для зовнішнього перевіряючого сервера. У цьому випадку сервіс нерідко повертає загальну помилку про невірне посилання.

• Перевірте, чи не закрито профіль, канал, публікацію або саму трансляцію.
• Переконайтеся, що ролик не видалено, не переміщено в чернетки та не замінено іншою публікацією.
• Перевірте вікове обмеження: воно може вимагати підтвердження віку або входу в акаунт.
• Вимкніть режим доступу лише для підписників, учасників або схвалених глядачів, якщо він увімкнений.
• Переконайтеся, що сторінка не показує форму логіна, попередження про контент або технічну заглушку.

Відкрийте посилання в приватному вікні без авторизації. Якщо замість цільової сторінки видно запит на вхід, змініть налаштування доступу або виберіть послугу, яка допускає такий тип цілі, якщо вона передбачена. Недолік перевірки в приватному вікні — вона не завжди виявляє регіональні та мережеві обмеження.

Врахуйте регіональні, мобільні та вбудовані адреси

Один об'єкт може мати десктопний, мобільний, локалізований і вбудований URL. Адреса із застосунку або webview іноді містить технічні сегменти, які не розпізнає API. Локалізована сторінка також може відкриватися інакше для перевіряючого сервера.

Відкрийте скопійоване посилання у звичайному браузері та дочекайтеся повного завантаження. Для запиту використовуйте публічну веб-адресу з адресного рядка. Якщо контент обмежений за регіоном, приберіть обмеження, якщо це дозволяють налаштування майданчика, або не надсилайте таку ціль у послугу, якій потрібен публічний доступ.

Публічне веб-посилання без авторизації та проміжних екранів — найнадійніший варіант для перевірки API.

Виключіть пошкодження URL під час надсилання запиту

Посилання може бути правильним до відправки, але змінитися під час серіалізації JSON, збирання query-параметрів, відправки form-data або повторного кодування. Особливо чутливі символи &, ?, # і %. Наприклад, амперсанд в URL може стати роздільником параметрів самого запиту, якщо адреса передається без потрібного кодування.

• Порівняйте вихідний URL зі значенням у фактичному HTTP-запиті.
• Перевірте тіло запиту в логах клієнта, проксі або інструментах розробника.
• Для JSON використовуйте штатну серіалізацію, а не ручне збирання рядка.
• Не кодуйте URL двічі, якщо бібліотека робить це автоматично.
• Перевірте обробку кирилиці в шляху та параметрах адреси.

Логи допомагають швидко знайти розбіжність, але мають недолік: у них можуть потрапити ключі API, токени та персональні дані. Маскуйте чутливі значення до запису та передачі логів.

Звірте майданчик, ідентифікатор послуги та параметри замовлення

Деякі API спочатку перевіряють послугу, а потім домен і тип посилання. URL іншого майданчика, застарілий service_id або невірний target_type можуть призвести до тієї ж помилки «невірне посилання». У такому разі змінювати саму адресу марно, поки не виправлено параметри замовлення.

Оновлюйте каталог послуг через метод API, якщо він передбачений. Кеш зі старим списком може зберігати вимкнену послугу або її попередні вимоги. Часте оновлення каталогу має недолік: воно збільшує кількість запитів і може зіткнутися з лімітом частоти. Використовуйте кеш з обмеженим терміном зберігання та оновлюйте його після помилок валідації.

Перевіряйте посилання по порядку перед повторною відправкою

1. Скопіюйте повний URL без тексту, пробілів і прихованих символів.
2. Відкрийте його в приватному вікні без входу в акаунт.
3. Перевірте, що сторінка не закрита, не видалена і не вимагає логіна.
4. Переконайтеся, що немає вікового, підписного або регіонального обмеження.
5. Розгорніть коротке посилання до кінцевої публічної адреси.
6. Зіставте об'єкт в URL з послугою: канал, відео, трансляція або публікація.
7. Звірте майданчик, service_id і target_type з актуальним каталогом послуг.
8. Перевірте фактичне тіло HTTP-запиту та кодування URL.
9. Збережіть повну відповідь API та ідентифікатор запиту без токенів і приватних даних.

Якщо після цих перевірок помилка зберігається, передавайте в підтримку посилання в очищеному вигляді, ідентифікатор послуги, час запиту, статус HTTP і повний текст відповіді API. Це дозволить відрізнити проблему URL від обмеження конкретної послуги або збою перевірки на боці сервісу.