Ошибка «неверная ссылка» в 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 от ограничения конкретной услуги или сбоя проверки на стороне сервиса.