Resolvendo "URIError: URI malformed" e erros comuns de URL: Um Guia Completo

URLs (Uniform Resource Locators) são os endereços da web. Embora pareçam simples, existem regras rígidas sobre quais caracteres são permitidos. Quando essas regras são quebradas, você encontra erros como URIError: URI malformed, TypeError: Failed to construct 'URL': Invalid URL, ou simplesmente um link quebrado que leva a um erro 404.

Neste guia, vamos mergulhar nos erros de URL mais comuns e como resolvê-los em JavaScript e outros ambientes.

---

1. Mensagens de erro de URL comuns

Dependendo do que você está fazendo, poderá encontrar estes erros:

• JavaScript (decodeURIComponent): URIError: URI malformed
• JavaScript (new URL()): TypeError: Failed to construct 'URL': Invalid URL
• Python (urllib): ValueError: Invalid URL
• Java (URLDecoder): java.lang.IllegalArgumentException: URLDecoder: Incomplete % sequence

---

2. Principais causas e soluções

2.1 "URIError: URI malformed"

Este erro ocorre no JavaScript quando decodeURI() ou decodeURIComponent() encontra uma sequência de codificação percentual (percent encoding error) que é inválida. Isso geralmente acontece se um sinal % não for seguido por dois dígitos hexadecimais, ou se a sequência representar um caractere UTF-8 inválido.

O Erro:

decodeURIComponent("%") // URIError: URI malformed
decodeURIComponent("%E0%A4%A") // URIError: URI malformed (Incompleto)

A Solução:

1. Escapar sinais % isolados: Se a sua string contiver sinais % literais que não fazem parte de uma sequência codificada, você deve escapá-los como %25.
2. Verificar truncamento: Certifique-se de que a URL não foi cortada no meio de uma sequência (por exemplo, por um limite de campo no banco de dados ou um parâmetro de consulta muito longo).
3. Usar Try-Catch: Sempre envolva a decodificação em um bloco try-catch.

function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    console.error("Malformed URL (URL malformada):", str);
    return str; // Retorna a string original se a decodificação falhar
  }
}

2.2 encodeURI vs. encodeURIComponent

Um erro comum é usar a função de codificação errada, levando a erros de invalid URL quando o servidor recebe a requisição.

• encodeURI(): Usado para a URL inteira. NÃO codifica caracteres que têm significado especial na estrutura da URL (como :, /, ?, #, &, =).
• encodeURIComponent(): Usado para parâmetros individuais (como uma consulta de pesquisa ou um nome de arquivo). Codifica tudo, exceto alguns caracteres básicos.

O Erro:

const url = "https://example.com/search?q=" + encodeURI("azul/verde");
// Resultado: https://example.com/search?q=azul/verde (O / quebra o parâmetro)

A Forma Correta:

const url = "https://example.com/search?q=" + encodeURIComponent("azul/verde");
// Resultado: https://example.com/search?q=azul%2Fverde (Correto!)

2.3 "TypeError: Invalid URL"

Isso acontece quando você passa uma string para o construtor URL que não é uma URL absoluta válida (por exemplo, falta o protocolo como https://).

O Erro:

new URL("www.google.com") // TypeError: Invalid URL

A Solução: Certifique-se de que a URL seja absoluta ou forneça uma URL base como segundo argumento.

new URL("https://www.google.com") // Correto
new URL("/caminho", "https://example.com") // Correto

2.4 Erros de codificação percentual (Espaços e caracteres especiais)

URLs não podem conter espaços. Embora alguns navegadores convertam automaticamente espaços em %20 ou +, confiar nesse comportamento é arriscado.

A Solução: Sempre codifique dados dinâmicos.

• Espaço -> %20 (Padrão)
• Espaço -> + (Válido apenas em query strings, como ?q=ola+mundo)

---

3. Solução de problemas avançada

3.1 Codificação dupla (Double Encoding)

Se você codificar uma string duas vezes, ela se tornará uma bagunça. Por exemplo, um espaço torna-se %20 e, depois, %2520. Solução: Acompanhe onde a codificação acontece. Codifique os dados apenas uma vez, logo antes de anexá-los à URL.

3.2 Codificações não UTF-8

A web moderna usa UTF-8. Se você encontrar um sistema antigo que usa GBK ou Latin1 para parâmetros de URL, o decodeURIComponent falhará ou produzirá "mojibake" (texto corrompido). Solução: Você pode precisar de uma biblioteca como iconv-lite para lidar com codificações legadas antes de processar a URL.

---

4. Prevenção e melhores práticas

1. Use a API URL: Em vez de concatenação manual de strings, use as APIs integradas URL e URLSearchParams. Elas lidam com a codificação de forma automática e correta.
2. Seja específico: Use encodeURIComponent para valores de parâmetros e encodeURI para o caminho base.
3. Sanitize a entrada: Se os usuários estiverem fornecendo URLs, valide-as usando o construtor URL em um bloco try-catch.

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;  
  }
}

---

5. FAQ: Perguntas frequentes

P: Qual é a diferença entre %20 e + para espaços?

R: %20 é a codificação padrão para o caractere de espaço em qualquer parte de um URI. + é uma convenção antiga específica para parâmetros de consulta (application/x-www-form-urlencoded). Use %20 para compatibilidade máxima.

P: Por que vejo %25 na minha URL?

R: %25 é a versão codificada do próprio caractere %. Isso geralmente acontece quando uma URL que já estava codificada é codificada novamente (codificação dupla).

Q: Como lidar com URLs com Emojis ou caracteres não latinos?

R: Use sempre encodeURIComponent. Ele converte corretamente os caracteres Unicode em uma sequência de bytes UTF-8 e, em seguida, codifica cada byte em percentual.

---

6. Ferramenta de verificação rápida

Está com dificuldades com uma malformed URL? Use nosso Codificador e Decodificador de URL. Ele pode:

• Validar instantaneamente se uma URL está bem formada.
• Comparar resultados de encodeURI e encodeURIComponent.
• Decodificar com segurança strings de consulta complexas.
• Lidar com Nomes de Domínio Internacionalizados (IDN).

---

Erros relacionados

• Resolvendo erros de 'Unexpected token in JSON'
• Como corrigir erros de 'invalid base64 string'
• Entendendo URIError: URI malformed