Erro "link inválido" na API: verificação da URL antes de criar o pedido

O que significa o erro "link inválido" na API

O erro "link inválido" significa que a API não conseguiu aceitar a URL no campo de destino do pedido. Nem sempre é um erro de digitação no endereço. O serviço pode rejeitar o link por formato inadequado, tipo de página, redirecionamento, restrições de acesso, codificação ou incompatibilidade entre a plataforma e o serviço.

A verificação geralmente ocorre antes da criação do pedido. A API recebe a URL, identifica o domínio e o caminho, e tenta reconhecer o objeto: canal, vídeo, transmissão, publicação ou perfil. Se uma dessas etapas falhar, o pedido não será criado. O texto genérico do erro por si só não mostra a causa — é preciso analisar a URL, os parâmetros do serviço e a resposta completa da API.

Relacione o texto do erro com a resposta da API

Diferentes APIs têm formulações e estruturas de resposta distintas. Às vezes o serviço retorna apenas uma mensagem, às vezes adiciona um código, o nome do campo ou um identificador da requisição. A resposta completa é mais útil que o status HTTP: mesmo com a requisição entregue com sucesso, a API pode rejeitar o próprio pedido no nível da validação de negócio.

Por exemplo, uma resposta típica pode ser assim: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Nesse caso, vale verificar justamente o valor do campo link. A variante {"error":"target_not_supported"} geralmente indica não um endereço quebrado, mas um tipo de objeto não suportado. Os nomes dos campos e códigos dependem da documentação específica.

Guarde o status da resposta, o corpo da resposta, o identificador do serviço e o request_id, se a API o retornar. Não inclua no ticket o token de acesso, cookies, assinaturas da requisição e parâmetros privados do link.

Verifique o formato da URL e o valor do campo da requisição

Um link que funciona no navegador pode não passar na verificação automática. Às vezes o campo recebe apenas o identificador do vídeo, o nickname sem domínio, um texto da mensagem ou um endereço encurtado. O erro também ocorre quando a URL é enviada não como string, mas como um objeto aninhado ou um array.

• Envie a URL pública completa com o protocolo https://.
• Verifique o domínio: ele deve pertencer à plataforma do serviço escolhido.
• Remova espaços nas extremidades, quebras de linha, emojis e texto após o link.
• Confira o nome do campo na documentação da API: link, url, target ou outro.
• Certifique-se de que a requisição envia um valor string, e não um objeto com a URL dentro.

Colar o endereço manualmente é prático, mas tem uma desvantagem: é fácil que um caractere invisível ou um trecho da legenda da publicação entre na string. Antes de enviar, limpe o valor, mas não altere o caminho e os parâmetros sem necessidade.

Expanda links curtos e remova redirecionamentos desnecessários

Endereços encurtados e links do botão "Compartilhar" costumam passar por um ou mais redirecionamentos. O navegador os abre automaticamente, mas a API do serviço de promoção pode não seguir os redirecionamentos, bloqueá-los ou receber uma página intermediária de autorização.

Para o pedido, é melhor usar o endereço canônico: aquele que aparece na barra de endereços após o carregamento completo da página desejada. As tags de campanha e os parâmetros de tempo de exibição nem sempre atrapalham, mas os parâmetros podem levar a outra visualização da página ou influenciar o reconhecimento do objeto.

A URL canônica tem uma desvantagem: às vezes é preciso obtê-la separadamente, especialmente após copiar o link de um aplicativo móvel. Em compensação, esse endereço é mais fácil de verificar manualmente e de comparar com as regras do serviço.

Escolha o link para o objeto que o serviço aceita

O serviço pode aceitar apenas um tipo de destino. Um pedido para canal não aceita o link de uma gravação de transmissão, e um serviço de visualizações de vídeo não aceita o perfil do autor. Externamente, ambas as URLs estão corretas, mas a API compara a estrutura do endereço com a finalidade do serviço e rejeita o objeto inadequado.

Consulte o catálogo de serviços: plataforma, categoria, target_type permitido e restrições. Se a API exige um parâmetro separado de tipo de destino, ele deve corresponder à URL. Não substitua o endereço do conteúdo por um link de busca, hashtag, coleção, página inicial ou painel do autor.

• Para promover um canal, envie a página do canal.
• Para visualizações, use o link de um vídeo ou gravação específica.
• Para uma transmissão ao vivo ativa, envie a URL da transmissão, se o serviço suportar o formato live.
• Para reações e outras ações com uma publicação, use o link direto da publicação.

Verifique a privacidade, os filtros de idade e a exigência de login

A API verifica não apenas a forma da URL, mas também a disponibilidade do destino. O conteúdo pode abrir para o dono do canal porque o navegador dele está autenticado, mas estar inacessível para um servidor de verificação externo. Nesse caso, o serviço costuma retornar um erro genérico de link inválido.

• Verifique se o perfil, o canal, a publicação ou a própria transmissão não estão fechados.
• Certifique-se de que o vídeo não foi excluído, movido para rascunhos ou substituído por outra publicação.
• Verifique a restrição de idade: ela pode exigir confirmação de idade ou login na conta.
• Desative o modo de acesso apenas para assinantes, membros ou espectadores aprovados, se estiver ativado.
• Certifique-se de que a página não exibe um formulário de login, um aviso de conteúdo ou uma página técnica provisória.

Abra o link em uma janela privada sem autenticação. Se em vez da página de destino aparecer uma solicitação de login, altere as configurações de acesso ou escolha um serviço que permita esse tipo de destino, se houver. A desvantagem da verificação em janela privada é que ela nem sempre revela restrições regionais e de rede.

Considere endereços regionais, móveis e incorporados

Um mesmo objeto pode ter URL de desktop, móvel, localizada e incorporada. O endereço do aplicativo ou do webview às vezes contém segmentos técnicos que a API não reconhece. Uma página localizada também pode abrir de forma diferente para o servidor de verificação.

Abra o link copiado em um navegador comum e aguarde o carregamento completo. Para a requisição, use o endereço web público da barra de endereços. Se o conteúdo for restrito por região, remova a restrição, se as configurações da plataforma permitirem, ou não envie esse destino para um serviço que exija acesso público.

Um link web público, sem autenticação e sem telas intermediárias, é a opção mais confiável para a verificação da API.

Evite a corrupção da URL ao enviar a requisição

O link pode estar correto antes do envio, mas mudar na serialização do JSON, na montagem dos query parameters, no envio de form-data ou na recodificação. Os caracteres &, ?, # e % são especialmente sensíveis. Por exemplo, um e comercial na URL pode se tornar separador de parâmetros da própria requisição se o endereço for enviado sem a codificação necessária.

• Compare a URL original com o valor na requisição HTTP real.
• Verifique o corpo da requisição nos logs do cliente, do proxy ou nas ferramentas de desenvolvedor.
• Para JSON, use a serialização nativa, e não a montagem manual da string.
• Não codifique a URL duas vezes se a biblioteca já faz isso automaticamente.
• Verifique o tratamento de caracteres cirílicos no caminho e nos parâmetros do endereço.

Os logs ajudam a encontrar rapidamente a divergência, mas têm uma desvantagem: podem conter chaves de API, tokens e dados pessoais. Mascare os valores sensíveis antes de gravar e transmitir os logs.

Confira a plataforma, o identificador do serviço e os parâmetros do pedido

Algumas APIs verificam primeiro o serviço e depois o domínio e o tipo de link. Uma URL de outra plataforma, um service_id desatualizado ou um target_type incorreto podem levar ao mesmo erro "link inválido". Nesse caso, mudar o próprio endereço é inútil enquanto os parâmetros do pedido não forem corrigidos.

Atualize o catálogo de serviços pelo método da API, se houver. Um cache com a lista antiga pode guardar um serviço desativado ou seus requisitos anteriores. A atualização frequente do catálogo tem uma desvantagem: aumenta o número de requisições e pode esbarrar no limite de taxa. Use um cache com prazo de armazenamento limitado e atualize-o após erros de validação.

Verifique o link em ordem antes de reenviar

1. Copie a URL completa sem texto, espaços e caracteres ocultos.
2. Abra-a em uma janela privada sem login na conta.
3. Verifique se a página não está fechada, excluída ou exigindo login.
4. Certifique-se de que não há restrição de idade, de assinatura ou regional.
5. Expanda o link curto até o endereço público final.
6. Compare o objeto na URL com o serviço: canal, vídeo, transmissão ou publicação.
7. Confira a plataforma, o service_id e o target_type com o catálogo de serviços atualizado.
8. Verifique o corpo real da requisição HTTP e a codificação da URL.
9. Guarde a resposta completa da API e o identificador da requisição sem tokens e dados privados.

Se após essas verificações o erro persistir, envie ao suporte o link em formato limpo, o identificador do serviço, o horário da requisição, o status HTTP e o texto completo da resposta da API. Isso permitirá distinguir um problema de URL de uma restrição do serviço específico ou de uma falha de verificação do lado do serviço.