Erreur « lien invalide » dans l'API : vérifier l'URL avant de créer une commande

Ce que signifie l'erreur « lien invalide » dans l'API

L'erreur « lien invalide » signifie que l'API n'a pas pu accepter l'URL dans le champ de cible de la commande. Ce n'est pas toujours une faute de frappe dans l'adresse. Le service peut rejeter le lien à cause d'un format inadapté, d'un type de page, d'une redirection, de restrictions d'accès, de l'encodage ou d'une inadéquation entre la plateforme et le service.

La vérification a généralement lieu avant la création de la commande. L'API reçoit l'URL, détermine le domaine et le chemin, puis tente d'identifier l'objet : chaîne, vidéo, diffusion, publication ou profil. Si l'une des étapes échoue, la commande ne sera pas créée. Le texte générique de l'erreur ne montre pas à lui seul la cause — il faut examiner l'URL, les paramètres du service et la réponse complète de l'API.

Faites correspondre le texte de l'erreur à la réponse de l'API

Selon les API, la formulation et la structure de la réponse diffèrent. Parfois le service renvoie uniquement un message, parfois il ajoute un code, le nom du champ ou un identifiant de requête. La réponse complète est plus utile que le statut HTTP : même si la requête est bien transmise, l'API peut rejeter la commande elle-même au niveau de la vérification métier.

Par exemple, une réponse typique peut ressembler à ceci : {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Ici, il faut vérifier précisément la valeur du champ link. La variante {"error":"target_not_supported"} indique le plus souvent non pas une adresse cassée, mais un type d'objet non pris en charge. Les noms des champs et des codes dépendent de la documentation spécifique.

Conservez le statut de la réponse, le corps de la réponse, l'identifiant du service et le request_id, si l'API le renvoie. N'ajoutez pas au ticket le jeton d'accès, les cookies, les signatures de requête et les paramètres privés du lien.

Vérifiez le format de l'URL et la valeur du champ de la requête

Un lien qui fonctionne dans le navigateur peut ne pas passer la vérification automatique. Il arrive que le champ ne contienne que l'identifiant de la vidéo, un pseudo sans domaine, un texte extrait d'un message ou une adresse raccourcie. L'erreur survient aussi lorsque l'URL est transmise non pas sous forme de chaîne, mais sous forme d'objet imbriqué ou de tableau.

• Transmettez l'URL publique complète avec le protocole https://.
• Vérifiez le domaine : il doit correspondre à la plateforme du service choisi.
• Supprimez les espaces en début et en fin, les retours à la ligne, les emojis et le texte après le lien.
• Vérifiez le nom du champ dans la documentation de l'API : link, url, target ou autre.
• Assurez-vous que la requête transmet une valeur de type chaîne, et non un objet contenant l'URL.

La saisie manuelle de l'adresse est pratique, mais elle a un inconvénient : un caractère invisible ou un fragment de légende de publication peut facilement se glisser dans la chaîne. Avant l'envoi, nettoyez la valeur, mais ne modifiez pas le chemin et les paramètres eux-mêmes sans nécessité.

Développez les liens courts et supprimez les redirections superflues

Les adresses raccourcies et les liens issus du bouton « Partager » passent souvent par une ou plusieurs redirections. Le navigateur les ouvre automatiquement, mais l'API du service de promotion peut ne pas suivre les redirections, les bloquer ou recevoir une page d'autorisation intermédiaire.

Pour la commande, il vaut mieux utiliser l'adresse canonique : celle qui apparaît dans la barre d'adresse après le chargement complet de la page souhaitée. Les balises de campagne et les paramètres de temps de visionnage ne gênent pas toujours, mais les paramètres peuvent mener à une autre présentation de la page ou influencer la reconnaissance de l'objet.

L'URL canonique a un inconvénient : il faut parfois l'obtenir séparément, surtout après avoir copié le lien depuis une application mobile. En revanche, une telle adresse est plus simple à vérifier manuellement et à comparer avec les règles du service.

Choisissez un lien vers l'objet accepté par le service

Le service peut n'accepter qu'un seul type de cible. Une commande pour une chaîne n'acceptera pas un lien vers un enregistrement de diffusion, et un service pour les vues d'une vidéo n'acceptera pas le profil de l'auteur. Extérieurement, les deux URL sont correctes, mais l'API compare la structure de l'adresse avec la destination du service et rejette l'objet inadapté.

Consultez le catalogue des services : plateforme, catégorie, target_type autorisé et restrictions. Si l'API exige un paramètre distinct pour le type de cible, il doit correspondre à l'URL. Ne remplacez pas l'adresse du contenu par un lien vers une recherche, un hashtag, une sélection, la page d'accueil ou l'espace de l'auteur.

• Pour la promotion d'une chaîne, transmettez la page de la chaîne.
• Pour les vues, utilisez le lien vers une vidéo ou un enregistrement précis.
• Pour une diffusion en direct active, transmettez l'URL de la diffusion si le service prend en charge le format live.
• Pour les réactions et autres actions sur une publication, utilisez le lien direct vers la publication.

Vérifiez la confidentialité, les filtres d'âge et l'exigence de connexion

L'API vérifie non seulement la forme de l'URL, mais aussi l'accessibilité de la cible. Le contenu peut s'ouvrir chez le propriétaire de la chaîne parce que son navigateur est autorisé, mais être inaccessible pour un serveur de vérification externe. Dans ce cas, le service renvoie souvent une erreur générique sur un lien invalide.

• Vérifiez si le profil, la chaîne, la publication ou la diffusion elle-même n'est pas fermé.
• Assurez-vous que la vidéo n'est pas supprimée, déplacée vers les brouillons ou remplacée par une autre publication.
• Vérifiez la restriction d'âge : elle peut exiger une confirmation d'âge ou une connexion au compte.
• Désactivez le mode d'accès réservé aux abonnés, aux membres ou aux spectateurs approuvés, s'il est activé.
• Assurez-vous que la page n'affiche pas de formulaire de connexion, d'avertissement sur le contenu ou de page technique de remplacement.

Ouvrez le lien dans une fenêtre privée sans autorisation. Si à la place de la page cible apparaît une demande de connexion, modifiez les paramètres d'accès ou choisissez un service qui autorise ce type de cible, s'il en existe un. L'inconvénient de la vérification en fenêtre privée est qu'elle ne détecte pas toujours les restrictions régionales et réseau.

Tenez compte des adresses régionales, mobiles et intégrées

Un même objet peut avoir une URL de bureau, mobile, localisée et intégrée. L'adresse issue de l'application ou d'une webview contient parfois des segments techniques que l'API ne reconnaît pas. Une page localisée peut également s'ouvrir différemment pour le serveur de vérification.

Ouvrez le lien copié dans un navigateur classique et attendez le chargement complet. Pour la requête, utilisez l'adresse web publique visible dans la barre d'adresse. Si le contenu est limité par région, supprimez la restriction si les paramètres de la plateforme le permettent, ou n'envoyez pas une telle cible à un service qui nécessite un accès public.

Un lien web public sans autorisation ni écrans intermédiaires est l'option la plus fiable pour la vérification par l'API.

Excluez toute altération de l'URL lors de l'envoi de la requête

Le lien peut être correct avant l'envoi, mais changer lors de la sérialisation JSON, de l'assemblage des paramètres de requête, de l'envoi en form-data ou d'un réencodage. Les caractères &, ?, # et % y sont particulièrement sensibles. Par exemple, l'esperluette dans l'URL peut devenir un séparateur de paramètres de la requête elle-même si l'adresse est transmise sans l'encodage nécessaire.

• Comparez l'URL d'origine avec la valeur présente dans la requête HTTP réelle.
• Vérifiez le corps de la requête dans les logs du client, du proxy ou des outils de développement.
• Pour le JSON, utilisez la sérialisation standard plutôt que l'assemblage manuel de la chaîne.
• N'encodez pas l'URL deux fois si la bibliothèque le fait automatiquement.
• Vérifiez le traitement du cyrillique dans le chemin et les paramètres de l'adresse.

Les logs aident à trouver rapidement l'écart, mais ils ont un inconvénient : des clés API, des jetons et des données personnelles peuvent s'y retrouver. Masquez les valeurs sensibles avant d'enregistrer et de transmettre les logs.

Vérifiez la plateforme, l'identifiant du service et les paramètres de la commande

Certaines API vérifient d'abord le service, puis le domaine et le type de lien. Une URL d'une autre plateforme, un service_id obsolète ou un target_type incorrect peuvent provoquer la même erreur « lien invalide ». Dans ce cas, il est inutile de modifier l'adresse elle-même tant que les paramètres de la commande ne sont pas corrigés.

Mettez à jour le catalogue des services via la méthode API, si elle est prévue. Un cache contenant une ancienne liste peut conserver un service désactivé ou ses exigences précédentes. La mise à jour fréquente du catalogue a un inconvénient : elle augmente le nombre de requêtes et peut se heurter à une limite de fréquence. Utilisez un cache à durée de conservation limitée et actualisez-le après des erreurs de validation.

Vérifiez le lien dans l'ordre avant de le renvoyer

1. Copiez l'URL complète sans texte, espaces ni caractères cachés.
2. Ouvrez-la dans une fenêtre privée sans connexion au compte.
3. Vérifiez que la page n'est pas fermée, supprimée ou soumise à une connexion.
4. Assurez-vous qu'il n'y a pas de restriction d'âge, d'abonnement ou de région.
5. Développez le lien court jusqu'à l'adresse publique finale.
6. Comparez l'objet dans l'URL avec le service : chaîne, vidéo, diffusion ou publication.
7. Vérifiez la plateforme, le service_id et le target_type par rapport au catalogue actuel des services.
8. Vérifiez le corps réel de la requête HTTP et l'encodage de l'URL.
9. Conservez la réponse complète de l'API et l'identifiant de requête sans jetons ni données privées.

Si après ces vérifications l'erreur persiste, transmettez au support le lien sous forme nettoyée, l'identifiant du service, l'heure de la requête, le statut HTTP et le texte complet de la réponse de l'API. Cela permettra de distinguer un problème d'URL d'une restriction propre à un service ou d'une défaillance de la vérification côté service.