Errore «link non valido» nell'API: verifica dell'URL prima di creare un ordine

Cosa significa l'errore «link non valido» nell'API

L'errore «link non valido» significa che l'API non è riuscita ad accettare l'URL nel campo di destinazione dell'ordine. Non sempre si tratta di un errore di battitura nell'indirizzo. Il servizio può rifiutare il link a causa di un formato non adatto, del tipo di pagina, di un reindirizzamento, di limitazioni di accesso, della codifica o della mancata corrispondenza tra la piattaforma e il servizio.

La verifica avviene di solito prima della creazione dell'ordine. L'API riceve l'URL, determina il dominio e il percorso, prova a riconoscere l'oggetto: canale, video, diretta, pubblicazione o profilo. Se una delle fasi non va a buon fine, l'ordine non verrà creato. Il testo generico dell'errore di per sé non mostra la causa: bisogna esaminare l'URL, i parametri del servizio e la risposta completa dell'API.

Confrontate il testo dell'errore con la risposta dell'API

Le diverse API hanno formulazione e struttura della risposta differenti. A volte il servizio restituisce solo un messaggio, a volte aggiunge un codice, il nome del campo o l'identificatore della richiesta. La risposta completa è più utile dello stato HTTP: anche se la richiesta viene consegnata con successo, l'API può rifiutare l'ordine stesso a livello di verifica business.

Ad esempio, una risposta tipica può essere così: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. In questo caso conviene controllare proprio il valore del campo link. La variante {"error":"target_not_supported"} indica più spesso non un indirizzo errato, ma un tipo di oggetto non supportato. I nomi dei campi e i codici dipendono dalla documentazione specifica.

Conservate lo stato della risposta, il corpo della risposta, l'identificatore del servizio e il request_id, se l'API lo restituisce. Non aggiungete al ticket il token di accesso, i cookie, le firme della richiesta e i parametri privati del link.

Verificate il formato dell'URL e il valore del campo della richiesta

Un link che funziona nel browser può non superare la verifica automatica. Nel campo a volte finisce solo l'identificatore del video, il nickname senza dominio, il testo di un messaggio o un indirizzo abbreviato. L'errore si verifica anche quando l'URL viene passato non come stringa, ma come oggetto annidato o array.

• Passate l'URL pubblico completo insieme al protocollo https://.
• Controllate il dominio: deve appartenere alla piattaforma del servizio scelto.
• Rimuovete gli spazi ai bordi, gli a capo, le emoji e il testo dopo il link.
• Confrontate il nome del campo con la documentazione dell'API: link, url, target o altro.
• Assicuratevi che nella richiesta venga passato un valore stringa e non un oggetto con l'URL all'interno.

L'inserimento manuale dell'indirizzo è comodo, ma ha un difetto: nella stringa può facilmente finire un carattere invisibile o un frammento della didascalia della pubblicazione. Prima dell'invio pulite il valore, ma non modificate il percorso e i parametri stessi senza necessità.

Espandete i link brevi e rimuovete i reindirizzamenti superflui

Gli indirizzi abbreviati e i link del pulsante «Condividi» passano spesso attraverso uno o più reindirizzamenti. Il browser li apre automaticamente, mentre l'API del servizio di promozione può non seguire i reindirizzamenti, bloccarli o ottenere una pagina intermedia di autorizzazione.

Per l'ordine è meglio usare l'indirizzo canonico: quello visibile nella barra degli indirizzi dopo il caricamento completo della pagina desiderata. Le etichette delle campagne e i parametri del tempo di visualizzazione non sempre danno fastidio, ma i parametri possono portare a una diversa rappresentazione della pagina o influire sul riconoscimento dell'oggetto.

L'URL canonico ha un difetto: a volte bisogna ottenerlo separatamente, soprattutto dopo aver copiato il link dall'app mobile. Però un indirizzo così è più facile da verificare manualmente e da confrontare con le regole del servizio.

Scegliete il link a un oggetto che il servizio accetta

Il servizio può accettare un solo tipo di destinazione. Un ordine per il canale non accetterà un link a una registrazione della diretta, e un servizio per le visualizzazioni del video non accetterà il profilo dell'autore. Esteriormente entrambi gli URL sono corretti, ma l'API confronta la struttura dell'indirizzo con la destinazione del servizio e rifiuta l'oggetto non adatto.

Consultate il catalogo dei servizi: piattaforma, categoria, target_type consentito e limitazioni. Se l'API richiede un parametro separato per il tipo di destinazione, deve corrispondere all'URL. Non sostituite l'indirizzo del contenuto con un link alla ricerca, a un hashtag, a una raccolta, alla pagina principale o al pannello dell'autore.

• Per la promozione del canale passate la pagina del canale.
• Per le visualizzazioni usate il link a un video o a una registrazione specifica.
• Per una diretta attiva passate l'URL della trasmissione, se il servizio supporta il formato live.
• Per le reazioni e altre azioni sulla pubblicazione usate il link diretto alla pubblicazione.

Verificate la privacy, i filtri di età e il requisito di accesso

L'API controlla non solo la forma dell'URL, ma anche la disponibilità della destinazione. Il contenuto può aprirsi per il proprietario del canale perché il suo browser è autorizzato, ma essere inaccessibile a un server di verifica esterno. In questo caso il servizio restituisce spesso un errore generico sul link non valido.

• Controllate se il profilo, il canale, la pubblicazione o la diretta stessa sono chiusi.
• Assicuratevi che il video non sia stato eliminato, spostato in bozza o sostituito da un'altra pubblicazione.
• Controllate la restrizione di età: può richiedere la conferma dell'età o l'accesso all'account.
• Disattivate la modalità di accesso riservata solo agli abbonati, ai membri o agli spettatori approvati, se è attiva.
• Assicuratevi che la pagina non mostri un modulo di login, un avviso sui contenuti o un segnaposto tecnico.

Aprite il link in una finestra privata senza autorizzazione. Se al posto della pagina di destinazione appare una richiesta di accesso, modificate le impostazioni di accesso oppure scegliete un servizio che consenta questo tipo di destinazione, se previsto. Il difetto della verifica in finestra privata è che non sempre rileva le limitazioni regionali e di rete.

Tenete conto degli indirizzi regionali, mobili e incorporati

Uno stesso oggetto può avere un URL desktop, mobile, localizzato e incorporato. L'indirizzo dall'app o dalla webview a volte contiene segmenti tecnici che l'API non riconosce. Anche la pagina localizzata può aprirsi diversamente per il server di verifica.

Aprite il link copiato in un browser normale e attendete il caricamento completo. Per la richiesta usate l'indirizzo web pubblico dalla barra degli indirizzi. Se il contenuto è limitato per regione, rimuovete la limitazione se le impostazioni della piattaforma lo consentono, oppure non inviate tale destinazione a un servizio che richiede accesso pubblico.

Un link web pubblico senza autorizzazione e senza schermate intermedie è la variante più affidabile per la verifica dell'API.

Escludete la corruzione dell'URL durante l'invio della richiesta

Il link può essere corretto prima dell'invio, ma cambiare durante la serializzazione JSON, la composizione dei parametri query, l'invio di form-data o la ricodifica. Sono particolarmente sensibili i caratteri &, ?, # e %. Ad esempio, la e commerciale nell'URL può diventare un separatore di parametri della richiesta stessa, se l'indirizzo viene passato senza la codifica necessaria.

• Confrontate l'URL originale con il valore nella richiesta HTTP effettiva.
• Controllate il corpo della richiesta nei log del client, del proxy o negli strumenti per sviluppatori.
• Per il JSON usate la serializzazione standard, non la composizione manuale della stringa.
• Non codificate l'URL due volte, se la libreria lo fa automaticamente.
• Controllate la gestione del cirillico nel percorso e nei parametri dell'indirizzo.

I log aiutano a trovare rapidamente la discrepanza, ma hanno un difetto: possono contenere chiavi API, token e dati personali. Mascherate i valori sensibili prima di registrarli e trasmetterli.

Confrontate la piattaforma, l'identificatore del servizio e i parametri dell'ordine

Alcune API verificano prima il servizio, poi il dominio e il tipo di link. Un URL di un'altra piattaforma, un service_id obsoleto o un target_type errato possono portare allo stesso errore «link non valido». In tal caso è inutile cambiare l'indirizzo stesso finché non sono corretti i parametri dell'ordine.

Aggiornate il catalogo dei servizi tramite il metodo API, se previsto. La cache con un vecchio elenco può conservare un servizio disattivato o i suoi requisiti precedenti. L'aggiornamento frequente del catalogo ha un difetto: aumenta il numero di richieste e può scontrarsi con il limite di frequenza. Usate una cache con un periodo di conservazione limitato e aggiornatela dopo gli errori di validazione.

Verificate il link in ordine prima di un nuovo invio

1. Copiate l'URL completo senza testo, spazi e caratteri nascosti.
2. Apritelo in una finestra privata senza accedere all'account.
3. Controllate che la pagina non sia chiusa, eliminata o che richieda il login.
4. Assicuratevi che non ci siano restrizioni di età, di abbonamento o regionali.
5. Espandete il link breve fino all'indirizzo pubblico finale.
6. Confrontate l'oggetto nell'URL con il servizio: canale, video, diretta o pubblicazione.
7. Confrontate la piattaforma, il service_id e il target_type con il catalogo dei servizi aggiornato.
8. Controllate il corpo effettivo della richiesta HTTP e la codifica dell'URL.
9. Conservate la risposta completa dell'API e l'identificatore della richiesta senza token e dati privati.

Se dopo queste verifiche l'errore persiste, inviate al supporto il link in forma ripulita, l'identificatore del servizio, l'ora della richiesta, lo stato HTTP e il testo completo della risposta dell'API. Questo permetterà di distinguere un problema dell'URL da una limitazione di un servizio specifico o da un guasto della verifica lato servizio.