Fehler „ungültiger Link“ in der API: URL-Prüfung vor dem Erstellen einer Bestellung

Was der Fehler „ungültiger Link“ in der API bedeutet

Der Fehler „ungültiger Link“ bedeutet, dass die API die URL im Feld für das Bestellziel nicht akzeptieren konnte. Das ist nicht immer ein Tippfehler in der Adresse. Der Dienst kann den Link wegen eines unpassenden Formats, Seitentyps, einer Weiterleitung, Zugriffsbeschränkungen, der Kodierung oder einer Nichtübereinstimmung zwischen Plattform und Service ablehnen.

Die Prüfung erfolgt in der Regel vor dem Erstellen der Bestellung. Die API erhält die URL, bestimmt Domain und Pfad und versucht, das Objekt zu erkennen: Kanal, Video, Livestream, Beitrag oder Profil. Wenn einer der Schritte fehlschlägt, wird die Bestellung nicht erstellt. Der allgemeine Fehlertext allein zeigt die Ursache nicht — man muss die URL, die Service-Parameter und die vollständige API-Antwort prüfen.

Fehlertext mit der API-Antwort abgleichen

Bei verschiedenen APIs unterscheiden sich Formulierung und Struktur der Antwort. Manchmal gibt der Dienst nur eine Meldung zurück, manchmal fügt er einen Code, einen Feldnamen oder eine Anfrage-ID hinzu. Die vollständige Antwort ist nützlicher als der HTTP-Status: Selbst wenn die Anfrage erfolgreich zugestellt wurde, kann die API die Bestellung selbst auf Ebene der Geschäftsprüfung ablehnen.

Eine typische Antwort kann beispielsweise so aussehen: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Hier sollte man genau den Wert des Feldes link prüfen. Die Variante {"error":"target_not_supported"} weist eher nicht auf eine fehlerhafte Adresse hin, sondern auf einen nicht unterstützten Objekttyp. Die Namen der Felder und Codes hängen von der jeweiligen Dokumentation ab.

Speichern Sie den Antwortstatus, den Antworttext, die Service-ID und die request_id, falls die API sie zurückgibt. Fügen Sie dem Ticket keine Zugriffstoken, Cookies, Anfragesignaturen und privaten Link-Parameter hinzu.

URL-Format und Wert des Anfragefelds prüfen

Ein im Browser funktionierender Link kann die maschinelle Prüfung nicht bestehen. Manchmal gelangt nur die Video-ID, ein Nickname ohne Domain, Text aus einer Nachricht oder eine gekürzte Adresse in das Feld. Der Fehler entsteht auch dann, wenn die URL nicht als String, sondern als verschachteltes Objekt oder Array übergeben wird.

• Übergeben Sie die vollständige öffentliche URL einschließlich des Protokolls https://.
• Prüfen Sie die Domain: Sie muss zur Plattform des gewählten Services gehören.
• Entfernen Sie Leerzeichen am Rand, Zeilenumbrüche, Emojis und Text nach dem Link.
• Vergleichen Sie den Feldnamen mit der API-Dokumentation: link, url, target oder ein anderer.
• Stellen Sie sicher, dass in der Anfrage ein String-Wert und kein Objekt mit einer URL darin übergeben wird.

Das manuelle Einfügen der Adresse ist bequem, hat aber einen Nachteil: Leicht gelangt ein unsichtbares Zeichen oder ein Fragment der Beitragsbeschreibung in die Zeichenkette. Bereinigen Sie den Wert vor dem Senden, ändern Sie aber den Pfad und die Parameter selbst nicht ohne Notwendigkeit.

Kurzlinks auflösen und überflüssige Weiterleitungen entfernen

Gekürzte Adressen und Links aus der Schaltfläche „Teilen“ durchlaufen oft eine oder mehrere Weiterleitungen. Der Browser öffnet sie automatisch, aber die API des Promotion-Dienstes folgt den Weiterleitungen möglicherweise nicht, blockiert sie oder erhält eine Zwischenseite zur Anmeldung.

Für die Bestellung ist die kanonische Adresse besser geeignet: diejenige, die nach dem vollständigen Laden der gewünschten Seite in der Adressleiste sichtbar ist. Kampagnen-Tags und Parameter zur Wiedergabezeit stören nicht immer, aber Parameter können zu einer anderen Darstellung der Seite führen oder die Erkennung des Objekts beeinflussen.

Die kanonische URL hat einen Nachteil: Sie muss manchmal separat ermittelt werden, insbesondere nach dem Kopieren eines Links aus einer mobilen App. Dafür lässt sich eine solche Adresse leichter manuell prüfen und mit den Regeln des Services abgleichen.

Einen Link zu einem Objekt wählen, das der Service akzeptiert

Ein Service kann nur einen Zieltyp akzeptieren. Eine Bestellung für einen Kanal akzeptiert keinen Link zu einer Live-Aufzeichnung, und ein Service für Videoaufrufe akzeptiert kein Autorenprofil. Äußerlich sind beide URLs korrekt, aber die API gleicht die Struktur der Adresse mit dem Zweck des Services ab und lehnt ein unpassendes Objekt ab.

Prüfen Sie das Service-Verzeichnis: Plattform, Kategorie, zulässiger target_type und Einschränkungen. Wenn die API einen separaten Parameter für den Zieltyp verlangt, muss er mit der URL übereinstimmen. Ersetzen Sie die Adresse des Inhalts nicht durch einen Link zur Suche, zu einem Hashtag, einer Sammlung, der Startseite oder dem Autorenkonto.

• Für die Kanal-Promotion übergeben Sie die Kanalseite.
• Für Aufrufe verwenden Sie den Link zu einem konkreten Video oder Beitrag.
• Für einen aktiven Livestream übergeben Sie die URL der Übertragung, wenn der Service das Live-Format unterstützt.
• Für Reaktionen und andere Aktionen mit einem Beitrag verwenden Sie den direkten Link zum Beitrag.

Privatsphäre, Altersfilter und Anmeldeanforderung prüfen

Die API prüft nicht nur die Form der URL, sondern auch die Verfügbarkeit des Ziels. Inhalte können für den Kanalinhaber sichtbar sein, weil sein Browser angemeldet ist, für einen externen Prüfserver aber nicht erreichbar sein. In diesem Fall gibt der Dienst häufig einen allgemeinen Fehler über einen ungültigen Link zurück.

• Prüfen Sie, ob Profil, Kanal, Beitrag oder die Übertragung selbst gesperrt sind.
• Stellen Sie sicher, dass das Video nicht gelöscht, in Entwürfe verschoben oder durch einen anderen Beitrag ersetzt wurde.
• Prüfen Sie die Altersbeschränkung: Sie kann eine Altersbestätigung oder Anmeldung im Konto erfordern.
• Deaktivieren Sie den Zugriffsmodus nur für Abonnenten, Mitglieder oder freigegebene Zuschauer, falls er aktiviert ist.
• Stellen Sie sicher, dass die Seite kein Anmeldeformular, keine Inhaltswarnung und keinen technischen Platzhalter anzeigt.

Öffnen Sie den Link in einem privaten Fenster ohne Anmeldung. Wenn statt der Zielseite eine Anmeldeaufforderung erscheint, ändern Sie die Zugriffseinstellungen oder wählen Sie einen Service, der diesen Zieltyp zulässt, sofern einer vorgesehen ist. Der Nachteil der Prüfung im privaten Fenster ist, dass sie regionale und netzwerkbedingte Einschränkungen nicht immer erkennt.

Regionale, mobile und eingebettete Adressen berücksichtigen

Ein Objekt kann eine Desktop-, mobile, lokalisierte und eingebettete URL haben. Eine Adresse aus einer App oder einem Webview enthält manchmal technische Segmente, die die API nicht erkennt. Auch eine lokalisierte Seite kann für den Prüfserver anders erscheinen.

Öffnen Sie den kopierten Link in einem normalen Browser und warten Sie, bis er vollständig geladen ist. Verwenden Sie für die Anfrage die öffentliche Webadresse aus der Adressleiste. Wenn der Inhalt regional beschränkt ist, heben Sie die Beschränkung auf, sofern die Einstellungen der Plattform dies zulassen, oder senden Sie ein solches Ziel nicht an einen Service, der öffentlichen Zugriff benötigt.

Ein öffentlicher Weblink ohne Anmeldung und Zwischenbildschirme ist die zuverlässigste Variante für die API-Prüfung.

Eine Beschädigung der URL beim Senden der Anfrage ausschließen

Der Link kann vor dem Senden korrekt sein, sich aber bei der JSON-Serialisierung, beim Zusammenbauen von Query-Parametern, beim Senden von form-data oder bei der erneuten Kodierung ändern. Besonders empfindlich sind die Zeichen &, ?, # und %. Beispielsweise kann ein Ampersand in der URL zum Trennzeichen der Parameter der Anfrage selbst werden, wenn die Adresse ohne die erforderliche Kodierung übergeben wird.

• Vergleichen Sie die ursprüngliche URL mit dem Wert in der tatsächlichen HTTP-Anfrage.
• Prüfen Sie den Anfrageinhalt in den Logs des Clients, des Proxys oder in den Entwicklertools.
• Verwenden Sie für JSON die standardmäßige Serialisierung statt des manuellen Zusammenbaus einer Zeichenkette.
• Kodieren Sie die URL nicht doppelt, wenn die Bibliothek dies automatisch tut.
• Prüfen Sie die Verarbeitung von kyrillischen Zeichen im Pfad und in den Adressparametern.

Logs helfen, Abweichungen schnell zu finden, haben aber einen Nachteil: In ihnen können API-Schlüssel, Token und personenbezogene Daten landen. Maskieren Sie sensible Werte, bevor Sie Logs schreiben und übertragen.

Plattform, Service-ID und Bestellparameter abgleichen

Manche APIs prüfen zuerst den Service und dann die Domain und den Linktyp. Eine URL einer anderen Plattform, eine veraltete service_id oder ein falscher target_type können zum selben Fehler „ungültiger Link“ führen. In diesem Fall ist es sinnlos, die Adresse selbst zu ändern, solange die Bestellparameter nicht korrigiert sind.

Aktualisieren Sie den Service-Katalog über die API-Methode, falls eine vorgesehen ist. Ein Cache mit einer alten Liste kann einen deaktivierten Service oder dessen frühere Anforderungen enthalten. Die häufige Aktualisierung des Katalogs hat einen Nachteil: Sie erhöht die Anzahl der Anfragen und kann auf ein Ratenlimit stoßen. Verwenden Sie einen Cache mit begrenzter Speicherdauer und aktualisieren Sie ihn nach Validierungsfehlern.

Den Link vor dem erneuten Senden der Reihe nach prüfen

1. Kopieren Sie die vollständige URL ohne Text, Leerzeichen und versteckte Zeichen.
2. Öffnen Sie sie in einem privaten Fenster ohne Anmeldung im Konto.
3. Prüfen Sie, dass die Seite nicht gesperrt, nicht gelöscht ist und keine Anmeldung erfordert.
4. Stellen Sie sicher, dass keine Alters-, Abo- oder regionale Beschränkung besteht.
5. Lösen Sie den Kurzlink bis zur endgültigen öffentlichen Adresse auf.
6. Gleichen Sie das Objekt in der URL mit dem Service ab: Kanal, Video, Übertragung oder Beitrag.
7. Vergleichen Sie Plattform, service_id und target_type mit dem aktuellen Service-Katalog.
8. Prüfen Sie den tatsächlichen Inhalt der HTTP-Anfrage und die Kodierung der URL.
9. Speichern Sie die vollständige API-Antwort und die Anfrage-ID ohne Token und private Daten.

Wenn der Fehler nach diesen Prüfungen weiterhin besteht, übermitteln Sie dem Support den Link in bereinigter Form, die Service-ID, den Zeitpunkt der Anfrage, den HTTP-Status und den vollständigen Text der API-Antwort. So lässt sich ein URL-Problem von einer Einschränkung des konkreten Services oder einem Prüffehler auf Seiten des Dienstes unterscheiden.