Foutmelding «ongeldige link» in de API: URL controleren vóór het aanmaken van een bestelling

Wat de foutmelding «ongeldige link» in de API betekent

De foutmelding «ongeldige link» betekent dat de API de URL in het doelveld van de bestelling niet kon accepteren. Dit is niet altijd een typefout in het adres. De service kan een link afwijzen vanwege een ongeschikt formaat, een verkeerd paginatype, een redirect, toegangsbeperkingen, codering of een mismatch tussen platform en service.

De controle vindt meestal plaats vóór het aanmaken van de bestelling. De API ontvangt de URL, bepaalt het domein en het pad en probeert het object te herkennen: kanaal, video, livestream, publicatie of profiel. Als een van deze stappen mislukt, wordt de bestelling niet aangemaakt. De algemene fouttekst op zichzelf toont de oorzaak niet — je moet de URL, de serviceparameters en het volledige API-antwoord bekijken.

Vergelijk de fouttekst met het API-antwoord

De formulering en structuur van het antwoord verschillen per API. Soms retourneert de service alleen een bericht, soms voegt het een code, een veldnaam of een request-id toe. Het volledige antwoord is nuttiger dan de HTTP-status: zelfs bij een succesvol afgeleverd verzoek kan de API de bestelling zelf afwijzen op het niveau van de bedrijfscontrole.

Een typisch antwoord kan er bijvoorbeeld zo uitzien: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Hier moet je vooral de waarde van het veld link controleren. De variant {"error":"target_not_supported"} wijst vaker niet op een kapot adres, maar op een niet-ondersteund objecttype. De namen van velden en codes hangen af van de specifieke documentatie.

Bewaar de responsstatus, de responsbody, het service-id en de request_id als de API die retourneert. Voeg geen toegangstoken, cookies, verzoekhandtekeningen of privéparameters van de link toe aan het ticket.

Controleer het URL-formaat en de waarde van het verzoekveld

Een link die in de browser werkt, kan de machinale controle niet doorstaan. Soms komt alleen een video-id in het veld terecht, een nicknaam zonder domein, tekst uit een bericht of een verkort adres. De fout ontstaat ook wanneer de URL niet als string wordt doorgegeven, maar als genest object of als array.

• Geef de volledige openbare URL door inclusief het protocol https://.
• Controleer het domein: het moet bij het platform van de gekozen service horen.
• Verwijder spaties aan het begin en einde, regeleinden, emoji's en tekst na de link.
• Vergelijk de veldnaam met de API-documentatie: link, url, target of iets anders.
• Zorg ervoor dat in het verzoek een stringwaarde wordt doorgegeven en geen object met een URL erin.

Handmatig plakken van een adres is handig, maar heeft een nadeel: er belandt gemakkelijk een onzichtbaar teken of een fragment van een publicatiebeschrijving in de string. Maak de waarde schoon vóór het verzenden, maar wijzig het pad en de parameters zelf niet zonder noodzaak.

Vouw korte links uit en verwijder overbodige redirects

Verkorte adressen en links van de knop «Delen» gaan vaak door een of meer redirects. De browser opent ze automatisch, maar de API van de promotieservice volgt de doorverwijzingen mogelijk niet, blokkeert ze of krijgt een tussenliggende autorisatiepagina.

Voor een bestelling kun je beter het canonieke adres gebruiken: het adres dat zichtbaar is in de adresbalk nadat de gewenste pagina volledig is geladen. Campagnelabels en parameters voor de weergavetijd vormen niet altijd een probleem, maar parameters kunnen tot een andere weergave van de pagina leiden of de herkenning van het object beïnvloeden.

Een canonieke URL heeft een nadeel: je moet hem soms apart ophalen, vooral nadat je de link uit een mobiele app hebt gekopieerd. Maar zo'n adres is eenvoudiger handmatig te controleren en te vergelijken met de regels van de service.

Kies een link naar een object dat de service accepteert

Een service kan slechts één doeltype accepteren. Een bestelling voor een kanaal accepteert geen link naar een uitzendopname, en een service voor videoweergaven accepteert geen profiel van de maker. Uiterlijk zijn beide URL's correct, maar de API vergelijkt de structuur van het adres met het doel van de service en wijst een ongeschikt object af.

Controleer het serviceoverzicht: platform, categorie, toegestaan target_type en beperkingen. Als de API een aparte parameter voor het doeltype vereist, moet deze overeenkomen met de URL. Vervang het adres van de content niet door een link naar zoeken, een hashtag, een selectie, de startpagina of het dashboard van de maker.

• Voor het promoten van een kanaal geef je de kanaalpagina door.
• Voor weergaven gebruik je de link naar een specifieke video of opname.
• Voor een actieve livestream geef je de URL van de uitzending door als de service het live-formaat ondersteunt.
• Voor reacties en andere acties op een publicatie gebruik je de directe link naar de publicatie.

Controleer privacy, leeftijdsfilters en de vereiste van inloggen

De API controleert niet alleen de vorm van de URL, maar ook de beschikbaarheid van het doel. Content kan zichtbaar zijn voor de kanaaleigenaar omdat diens browser is geautoriseerd, maar ontoegankelijk zijn voor een externe controlerende server. In dat geval retourneert de service vaak een algemene fout over een ongeldige link.

• Controleer of het profiel, kanaal, de publicatie of de uitzending zelf niet privé is.
• Zorg ervoor dat de video niet is verwijderd, niet naar concepten is verplaatst en niet door een andere publicatie is vervangen.
• Controleer de leeftijdsbeperking: deze kan leeftijdsbevestiging of inloggen op een account vereisen.
• Schakel de toegangsmodus alleen voor abonnees, leden of goedgekeurde kijkers uit als deze is ingeschakeld.
• Zorg ervoor dat de pagina geen loginformulier, waarschuwing over content of technische placeholder toont.

Open de link in een privévenster zonder autorisatie. Als in plaats van de doelpagina een inlogverzoek verschijnt, wijzig dan de toegangsinstellingen of kies een service die dit type doel toestaat, als die beschikbaar is. Het nadeel van een controle in een privévenster is dat deze niet altijd regionale en netwerkbeperkingen aan het licht brengt.

Houd rekening met regionale, mobiele en ingesloten adressen

Eén object kan een desktop-, mobiele, gelokaliseerde en ingesloten URL hebben. Een adres uit een app of webview bevat soms technische segmenten die de API niet herkent. Een gelokaliseerde pagina kan er voor de controlerende server ook anders uitzien.

Open de gekopieerde link in een gewone browser en wacht tot de pagina volledig is geladen. Gebruik voor het verzoek het openbare webadres uit de adresbalk. Als de content regionaal beperkt is, verwijder dan de beperking als de instellingen van het platform dat toestaan, of stuur zo'n doel niet naar een service die openbare toegang vereist.

Een openbare weblink zonder autorisatie en tussenliggende schermen is de meest betrouwbare optie voor de API-controle.

Sluit beschadiging van de URL bij het verzenden van het verzoek uit

De link kan correct zijn vóór het verzenden, maar veranderen bij JSON-serialisatie, het samenstellen van queryparameters, het verzenden van form-data of hercodering. Vooral de tekens &, ?, # en % zijn gevoelig. Een ampersand in de URL kan bijvoorbeeld een scheidingsteken worden voor de parameters van het verzoek zelf, als het adres zonder de juiste codering wordt doorgegeven.

• Vergelijk de oorspronkelijke URL met de waarde in het daadwerkelijke HTTP-verzoek.
• Controleer de requestbody in de logs van de client, proxy of ontwikkelaarstools.
• Gebruik voor JSON de standaardserialisatie en geen handmatige stringopbouw.
• Codeer de URL niet dubbel als de bibliotheek dit automatisch doet.
• Controleer de verwerking van Cyrillisch in het pad en de parameters van het adres.

Logs helpen snel een afwijking te vinden, maar hebben een nadeel: er kunnen API-sleutels, tokens en persoonsgegevens in terechtkomen. Maskeer gevoelige waarden voordat je logs opslaat en doorgeeft.

Vergelijk het platform, het service-id en de bestelparameters

Sommige API's controleren eerst de service en daarna het domein en het linktype. Een URL van een ander platform, een verouderd service_id of een onjuist target_type kunnen tot dezelfde fout «ongeldige link» leiden. In dat geval heeft het geen zin het adres zelf te wijzigen zolang de bestelparameters niet zijn gecorrigeerd.

Werk de servicecatalogus bij via de API-methode, als die beschikbaar is. Een cache met een oude lijst kan een uitgeschakelde service of de vroegere vereisten ervan bevatten. Regelmatig bijwerken van de catalogus heeft een nadeel: het verhoogt het aantal verzoeken en kan tegen een frequentielimiet aanlopen. Gebruik een cache met een beperkte bewaartermijn en werk deze bij na validatiefouten.

Controleer de link stap voor stap vóór opnieuw verzenden

1. Kopieer de volledige URL zonder tekst, spaties en verborgen tekens.
2. Open deze in een privévenster zonder in te loggen op een account.
3. Controleer dat de pagina niet privé is, niet is verwijderd en geen login vereist.
4. Zorg ervoor dat er geen leeftijds-, abonnements- of regionale beperking is.
5. Vouw de korte link uit tot het uiteindelijke openbare adres.
6. Vergelijk het object in de URL met de service: kanaal, video, livestream of publicatie.
7. Vergelijk het platform, service_id en target_type met de actuele servicecatalogus.
8. Controleer de daadwerkelijke HTTP-requestbody en de codering van de URL.
9. Bewaar het volledige API-antwoord en de request-id zonder tokens en privégegevens.

Als de fout na deze controles aanhoudt, geef dan aan de support een opgeschoonde link, het service-id, het tijdstip van het verzoek, de HTTP-status en de volledige tekst van het API-antwoord. Zo kan een URL-probleem worden onderscheiden van een beperking van een specifieke service of een controlefout aan de kant van de service.