La codificación de URL explicada: %20, + y errores comunes

Qué es realmente la codificación de URL

La codificación de URL, o codificación porcentual, es la forma en que una URL transporta caracteres que no puede contener. Una URL solo admite un pequeño conjunto de letras ASCII, dígitos y signos. Todo lo demás —un espacio, una tilde, un emoji, una palabra en cirílico o en árabe— debe escribirse como % seguido de dos dígitos hexadecimales por cada byte.

El mismo truco se usa con caracteres que sí están permitidos pero significan algo. Un ? abre la consulta y un & separa parámetros, así que una búsqueda de pan & queso debe enviar el ampersand como %26, o el servidor verá dos parámetros en lugar de uno.

Ese es todo su trabajo: hacer que un valor sea seguro dentro de una URL sin cambiar su significado. No es compresión, ni cifrado, ni un filtro de seguridad.

Cómo un carácter se convierte en %XX

La codificación trabaja con bytes, no con caracteres. Primero el texto se pasa a bytes UTF-8 y después cada byte que lo necesita se escribe como % y su valor en hexadecimal.

Un carácter ASCII es un byte, así que un espacio (byte 32, hex 20) pasa a ser %20. Los caracteres fuera de ASCII ocupan de dos a cuatro bytes en UTF-8, y cada byte lleva su propio escape:

• ñ → bytes C3 B1 → %C3%B1
• € → bytes E2 82 AC → %E2%82%AC
• 😀 → bytes F0 9F 98 80 → %F0%9F%98%80

Decodificar invierte los pasos: se reúnen los bytes y se leen como UTF-8. Si los bytes se generaron con otro juego de caracteres, como Latin-1, sale texto ilegible: niño en lugar de niño. Todos los navegadores y frameworks modernos usan UTF-8, y tú también deberías.

Reservados, no reservados y por qué importa el contexto

El RFC 3986 divide los caracteres de una URL en dos grupos.

Los no reservados —A–Z a–z 0–9 - . _ ~— nunca necesitan codificarse. Hacerlo es válido pero inútil, y un buen codificador los deja tal cual.

Los reservados —: / ? # [ ] @ ! $ & ' ( ) * + , ; =— dan estructura a la URL. Codificar uno depende de dónde esté. La / entre segmentos de la ruta debe seguir siendo una barra; una / dentro de un nombre de archivo que pasas como parámetro debe ser %2F. Por eso no existe una única forma correcta de «codificar una URL»: se codifica cada parte según su destino.

encodeURIComponent frente a encodeURI

JavaScript tiene dos funciones integradas y elegir la equivocada es el error de URL más común.

Si aplicas encodeURI a un valor como a&b=c, el & y el = sobreviven y tu parámetro se convierte en dos. Si aplicas encodeURIComponent a una URL entera, se escapan todas las / y los : y el enlace deja de serlo. La regla: construye la URL por partes y codifica cada valor con encodeURIComponent, o mejor, deja que URLSearchParams lo haga por ti.

Otros lenguajes tienen la misma división: quote y quote_plus en Python, rawurlencode y urlencode en PHP. Nuestro codificador y decodificador de URL ofrece ambos modos para que veas la diferencia con tu propio texto.

¿+ o %20? La excepción de los formularios

En una ruta, un espacio es %20 y un + es solo un signo más. Pero los formularios HTML enviados con el tipo por defecto application/x-www-form-urlencoded codifican el espacio como + en la consulta, y los servidores lo decodifican de vuelta.

El problema aparece cuando se mezclan las dos convenciones. Un teléfono como +34 912 345 678 puesto en la consulta sin codificar llega como 34 912 345 678, porque el servidor leyó el + como espacio. La solución es codificar el más como %2B, cosa que hace cualquier codificador que siga las reglas de formularios. Si dudas de qué convención espera el otro lado, %20 para el espacio y %2B para el más son siempre seguros.

La doble codificación y el error %2520

%25 es el propio signo de porcentaje codificado. Así que cuando ves %2520 en una URL, es un %20 codificado por segunda vez: un valor pasó por un codificador cuando ya estaba codificado.

Suele ocurrir en una frontera: un framework codifica un parámetro que el código que lo llama ya había codificado, o una URL de redirección se codifica una vez para meterla en otra URL y luego otra vez una librería. El síntoma visible es un 404, una búsqueda del texto literal %20 o un nombre de archivo lleno de signos de porcentaje.

Decodificar dos veces recupera el original, pero la solución real es encontrar el segundo codificador y quitarlo. Codifica exactamente una vez, en el momento en que el valor entra en la URL.

Codificar no es escapar, ni cifrar

La codificación porcentual hace seguro un valor dentro de una URL. No hace nada por el HTML, el JavaScript o el SQL. En cuanto el servidor decodifica %3Cscript%3E vuelve a tener un <script> normal, así que la salida debe escaparse según su destino y las consultas a la base de datos siguen necesitando parámetros.

Tampoco es secreto. Cualquiera puede decodificar una URL, y las URL quedan en registros del servidor, historiales, herramientas de analítica y en la cabecera Referer de la página siguiente. Nunca pongas una contraseña, un token o datos personales en una consulta porque «parece revuelto». Lo mismo pasa con Base64, como explica nuestra guía de Base64.

Cuando la decodificación falla

La mayoría de los problemas con URL son uno de estos:

• «URIError: malformed URI sequence». Hay un % sin dos dígitos hexadecimales detrás o los bytes no son UTF-8 válido. Un signo de porcentaje literal debe enviarse como %25.
• Las tildes salen como ñ o �. Los bytes se escribieron en un juego de caracteres y se leyeron en otro. Asegúrate de que ambos lados usan UTF-8.
• Un parámetro se corta en un &. El valor no se codificó, o se codificó con encodeURI en lugar de encodeURIComponent.
• Los signos más se vuelven espacios. La decodificación de formularios trató el + como espacio. Codifica un más real como %2B.
• %2520, %253D y compañía. Doble codificación: busca el segundo codificador.

Pega la URL en un decodificador y mira cada parámetro por separado: el desglose suele dejar el problema claro en segundos.

Herramientas y guías relacionadas:

• Codificador y decodificador de URL - Codifica texto o una URL completa, decodifica %XX a texto y ve cada parámetro de la consulta.
• Codificador y decodificador Base64 - Codifica texto a Base64 o decodifícalo, con salida URL-safe y UTF-8 bien tratado.
• Base64 explicado: cómo funcionan la codificación y la decodificación

Preguntas frecuentes