Error «enlace no válido» en la API: verificación de la URL antes de crear un pedido

Qué significa el error «enlace no válido» en la API

El error «enlace no válido» significa que la API no pudo aceptar la URL en el campo de objetivo del pedido. No siempre se trata de una errata en la dirección. El servicio puede rechazar el enlace por un formato inadecuado, el tipo de página, una redirección, restricciones de acceso, la codificación o la falta de coincidencia entre la plataforma y el servicio.

La verificación suele realizarse antes de crear el pedido. La API recibe la URL, determina el dominio y la ruta, e intenta reconocer el objeto: canal, vídeo, transmisión, publicación o perfil. Si alguna de las etapas no se supera, el pedido no se creará. El texto genérico del error por sí solo no muestra la causa: hay que revisar la URL, los parámetros del servicio y la respuesta completa de la API.

Compare el texto del error con la respuesta de la API

En distintas API cambian la formulación y la estructura de la respuesta. A veces el servicio devuelve solo un mensaje, otras veces añade un código, el nombre del campo o un identificador de la solicitud. La respuesta completa es más útil que el estado HTTP: incluso si la solicitud se entrega correctamente, la API puede rechazar el propio pedido en la fase de validación de negocio.

Por ejemplo, una respuesta típica puede ser así: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Aquí conviene revisar precisamente el valor del campo link. La variante {"error":"target_not_supported"} suele indicar no una dirección rota, sino un tipo de objeto no compatible. Los nombres de los campos y los códigos dependen de la documentación concreta.

Guarde el estado de la respuesta, el cuerpo de la respuesta, el identificador del servicio y el request_id, si la API lo devuelve. No añada al ticket el token de acceso, las cookies, las firmas de la solicitud ni los parámetros privados del enlace.

Compruebe el formato de la URL y el valor del campo de la solicitud

Un enlace que funciona en el navegador puede no superar la verificación automática. A veces en el campo solo acaba el identificador del vídeo, el nombre de usuario sin dominio, el texto de un mensaje o una dirección acortada. El error también surge cuando la URL se envía no como cadena, sino como un objeto anidado o un array.

• Enviar la URL pública completa junto con el protocolo https://.
• Compruebe el dominio: debe pertenecer a la plataforma del servicio seleccionado.
• Elimine los espacios en los extremos, los saltos de línea, los emojis y el texto que haya después del enlace.
• Coteje el nombre del campo con la documentación de la API: link, url, target u otro.
• Asegúrese de que en la solicitud se envía un valor de tipo cadena y no un objeto con la URL dentro.

Pegar la dirección a mano es cómodo, pero tiene una desventaja: es fácil que en la cadena acabe un carácter invisible o un fragmento del texto de la publicación. Antes de enviar, limpie el valor, pero no modifique la propia ruta ni los parámetros sin necesidad.

Despliegue los enlaces cortos y elimine las redirecciones innecesarias

Las direcciones acortadas y los enlaces del botón «Compartir» suelen pasar por una o varias redirecciones. El navegador las abre automáticamente, pero la API del servicio de promoción puede no seguir las redirecciones, bloquearlas u obtener una página intermedia de autorización.

Para el pedido es mejor usar la dirección canónica: la que se ve en la barra de direcciones tras la carga completa de la página deseada. Las etiquetas de campaña y los parámetros de tiempo de visualización no siempre estorban, pero los parámetros pueden llevar a otra representación de la página o influir en el reconocimiento del objeto.

La URL canónica tiene una desventaja: a veces hay que obtenerla por separado, sobre todo después de copiar el enlace desde la aplicación móvil. En cambio, esa dirección es más fácil de verificar manualmente y de cotejar con las reglas del servicio.

Elija el enlace al objeto que acepta el servicio

El servicio puede aceptar solo un tipo de objetivo. Un pedido para un canal no aceptará un enlace a la grabación de una emisión, y un servicio para visualizaciones de un vídeo no aceptará el perfil del autor. Externamente ambas URL son correctas, pero la API compara la estructura de la dirección con la finalidad del servicio y rechaza el objeto inadecuado.

Consulte el catálogo de servicios: la plataforma, la categoría, el target_type admitido y las restricciones. Si la API requiere un parámetro aparte del tipo de objetivo, debe coincidir con la URL. No sustituya la dirección del contenido por un enlace a la búsqueda, un hashtag, una recopilación, la página principal o el panel del autor.

• Para promocionar un canal, envíe la página del canal.
• Para visualizaciones, use el enlace a un vídeo o una grabación concretos.
• Para una emisión activa, envíe la URL de la transmisión si el servicio admite el formato live.
• Para reacciones y otras acciones con una publicación, use el enlace directo a la publicación.

Compruebe la privacidad, los filtros de edad y el requisito de inicio de sesión

La API verifica no solo la forma de la URL, sino también la disponibilidad del objetivo. El contenido puede abrirse para el propietario del canal porque su navegador está autorizado, pero ser inaccesible para un servidor de verificación externo. En ese caso, el servicio suele devolver un error genérico sobre un enlace no válido.

• Compruebe si el perfil, el canal, la publicación o la propia transmisión están cerrados.
• Asegúrese de que el vídeo no se ha eliminado, no se ha movido a borradores ni se ha sustituido por otra publicación.
• Compruebe la restricción de edad: puede requerir confirmación de edad o inicio de sesión en la cuenta.
• Desactive el modo de acceso solo para suscriptores, miembros o espectadores aprobados, si está activado.
• Asegúrese de que la página no muestra un formulario de inicio de sesión, una advertencia sobre el contenido ni un aviso técnico provisional.

Abra el enlace en una ventana privada sin iniciar sesión. Si en lugar de la página de destino aparece una solicitud de inicio de sesión, cambie la configuración de acceso o elija un servicio que admita ese tipo de objetivo, si existe. La desventaja de la comprobación en una ventana privada es que no siempre detecta las restricciones regionales y de red.

Tenga en cuenta las direcciones regionales, móviles e incrustadas

Un mismo objeto puede tener una URL de escritorio, móvil, localizada e incrustada. La dirección de la aplicación o del webview a veces contiene segmentos técnicos que la API no reconoce. La página localizada también puede abrirse de forma distinta para el servidor de verificación.

Abra el enlace copiado en un navegador normal y espere a que se cargue por completo. Para la solicitud, use la dirección web pública de la barra de direcciones. Si el contenido está restringido por región, elimine la restricción si la configuración de la plataforma lo permite, o no envíe ese objetivo a un servicio que requiera acceso público.

Un enlace web público sin autorización ni pantallas intermedias es la opción más fiable para la verificación de la API.

Descarte la alteración de la URL al enviar la solicitud

El enlace puede ser correcto antes del envío, pero cambiar durante la serialización de JSON, el montaje de los parámetros de la query, el envío de form-data o una nueva codificación. Los caracteres &, ?, # y % son especialmente sensibles. Por ejemplo, el ampersand de la URL puede convertirse en separador de los parámetros de la propia solicitud si la dirección se envía sin la codificación necesaria.

• Compare la URL original con el valor de la solicitud HTTP real.
• Revise el cuerpo de la solicitud en los logs del cliente, del proxy o de las herramientas de desarrollo.
• Para JSON, use la serialización estándar en lugar de montar la cadena a mano.
• No codifique la URL dos veces si la biblioteca ya lo hace automáticamente.
• Compruebe el tratamiento del cirílico en la ruta y en los parámetros de la dirección.

Los logs ayudan a encontrar rápidamente la discrepancia, pero tienen una desventaja: pueden contener claves de API, tokens y datos personales. Enmascare los valores sensibles antes de registrar y transmitir los logs.

Coteje la plataforma, el identificador del servicio y los parámetros del pedido

Algunas API primero verifican el servicio y después el dominio y el tipo de enlace. Una URL de otra plataforma, un service_id obsoleto o un target_type incorrecto pueden provocar el mismo error «enlace no válido». En ese caso, cambiar la propia dirección no sirve de nada mientras no se corrijan los parámetros del pedido.

Actualice el catálogo de servicios mediante el método de la API, si está previsto. La caché con una lista antigua puede conservar un servicio desactivado o sus requisitos anteriores. La actualización frecuente del catálogo tiene una desventaja: aumenta el número de solicitudes y puede chocar con el límite de frecuencia. Use una caché con un tiempo de almacenamiento limitado y actualícela tras los errores de validación.

Verifique el enlace en orden antes de reenviarlo

1. Copie la URL completa sin texto, espacios ni caracteres ocultos.
2. Ábrala en una ventana privada sin iniciar sesión en la cuenta.
3. Compruebe que la página no está cerrada, no se ha eliminado y no requiere inicio de sesión.
4. Asegúrese de que no hay restricción de edad, de suscripción ni regional.
5. Despliegue el enlace corto hasta la dirección pública final.
6. Coteje el objeto de la URL con el servicio: canal, vídeo, transmisión o publicación.
7. Compare la plataforma, el service_id y el target_type con el catálogo de servicios actual.
8. Revise el cuerpo real de la solicitud HTTP y la codificación de la URL.
9. Guarde la respuesta completa de la API y el identificador de la solicitud sin tokens ni datos privados.

Si tras estas comprobaciones el error persiste, envíe al soporte el enlace en forma depurada, el identificador del servicio, la hora de la solicitud, el estado HTTP y el texto completo de la respuesta de la API. Esto permitirá distinguir un problema de la URL de una restricción del servicio concreto o de un fallo de la verificación en el lado del servicio.