URL Encoding (Percent-Encoding) Rules and Common Bugs
A URL can only carry a small set of ASCII characters. Everything else, and every character that would otherwise be mistaken for URL structure, has to be written as a percent sign followed by two hexadecimal digits. The rules are simple, but the places where people apply them wrongly are many, and the bugs they cause are quiet ones: a search term that loses its plus sign, a redirect that never arrives, a filename that turns into mojibake.
Reserved and unreserved characters
RFC 3986 splits ASCII into two useful groups. Unreserved characters never need encoding and mean the same thing encoded or not: letters A-Z a-z, digits, and the four marks - . _ ~. Reserved characters are the delimiters that give a URL its shape: : / ? # [ ] @ and the sub-delimiters ! $ & ' ( ) * + , ; =.
A reserved character is only "safe" when it is doing its structural job. A / separates path segments, a ? starts the query, & separates parameters, = separates a name from a value and # starts the fragment. If you want one of those characters to appear as data, for instance an ampersand inside a company name, you must encode it, otherwise the parser will read it as structure. Everything outside both groups (spaces, quotes, angle brackets, non-ASCII letters) must always be encoded.
How the encoding itself works
Percent-encoding operates on bytes, not characters. The text is first converted to UTF-8, and each byte that needs encoding becomes % plus two hex digits. A space is byte 0x20, so it becomes %20. The letter é is two bytes in UTF-8, so it becomes %C3%A9. An emoji such as 😀 is four bytes: %F0%9F%98%80. These values come straight from running the encoders in JavaScript and Python, and you can reproduce them in the URL Encoder.
encodeURIComponent('é') // "%C3%A9"
encodeURIComponent('😀') // "%F0%9F%98%80"
urllib.parse.quote('é') # '%C3%A9' (Python)
Hex digits are case-insensitive, so %c3%a9 and %C3%A9 are equal, though uppercase is the conventional form. A decoder must reassemble the bytes and interpret them as UTF-8; decoding a lone %A9 gives invalid UTF-8, which is a common sign that somebody encoded in Latin-1 on the way in.
encodeURI versus encodeURIComponent
JavaScript ships two functions and choosing the wrong one is the most common mistake of all. encodeURIComponent is for a single piece: a query value, a path segment. It escapes every reserved character, leaving only letters, digits and - _ . ! ~ * ' ( ). encodeURI is for a whole URL that is already structured: it leaves : / ? # & = and friends alone and only escapes characters that are illegal anywhere.
encodeURI('https://a.com/a b?q=x&y=é#f')
// "https://a.com/a%20b?q=x&y=%C3%A9#f"
encodeURIComponent('x&y=1')
// "x%26y%3D1"
Two mistakes follow. Running encodeURIComponent on a whole URL produces https%3A%2F%2F..., which is no longer a URL at all. Running encodeURI on a parameter value leaves &, = and # intact, so a value like a&admin=true injects a second parameter. The URL Encoder offers both a component mode and a full-URL mode for exactly this reason; pick the one that matches what you are pasting.
Space: %20 or +?
Both appear in the wild because there are two specifications. In a generic URI, a space is %20 and a plus sign is simply a plus sign. In application/x-www-form-urlencoded, the format used by HTML forms and many query strings, a space is written as +, and a literal plus must be %2B. Servers that parse query strings as form data turn + into a space; a path is never parsed that way, so /my+file really means a file with a plus in its name.
The practical rule: use %20 unless you know the receiver expects form encoding, and always encode a literal plus as %2B. A phone number like +44 20 7946 0000 sent unencoded in a query arrives with a leading space instead of the plus, a classic silent bug. When decoding, the URL Encoder has a form-encoding toggle so you can read + as a space only when that is correct.
| Input | Generic URI | Form encoding |
|---|---|---|
| space | %20 | + |
| plus sign | + or %2B | %2B |
| ampersand | %26 | %26 |
| é | %C3%A9 | %C3%A9 |
Encode the parts, not the whole
The cleanest rule is: encode each value individually, then assemble. String-concatenate an already-encoded URL with raw user input and you have two layers of meaning mixed together. The safe way is to let a library build the query:
const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'café & crème 50% off');
url.toString();
// https://api.example.com/search?q=caf%C3%A9+%26+cr%C3%A8me+50%25+off
URLSearchParams uses form encoding, which is why spaces came out as +. That is valid for query strings, and every mainstream server decodes it. If you hand-build URLs, encode each value with encodeURIComponent and join with & yourself. Python has urllib.parse.urlencode and quote for the same purpose; note that quote leaves / unescaped by default, so pass safe='' when encoding a value that may contain slashes.
Paths, slashes and fragments
A path parameter that may contain a slash is a trap. A file called reports/2026 placed in /files/{name} must become /files/reports%2F2026 to remain one segment. Be aware that some web servers and proxies reject or normalise %2F in paths, so for arbitrary strings an ID or a query parameter is a safer design than embedding the text in the path.
The fragment (everything after #) is never sent to the server; the browser keeps it. So encoding matters for client-side code reading location.hash, but a server will never see it. Likewise, a # that you forgot to encode in a query value silently truncates the request: ?color=#ff0000 sends color= and nothing else.
Double encoding and its symptoms
Double encoding happens when already-encoded text is encoded again: %20 becomes %2520, because the percent sign itself is encoded as %25. You will see literal %20 showing up in file names or on screen. It usually means two layers (a framework and your own code, or a redirect and a link builder) each did their job. The fix is to encode exactly once, at the boundary where raw data enters the URL, and never encode something you received from a URL without decoding it first.
The opposite fault, decoding twice, is a security matter. If a filter checks the string after one decode and the application decodes again, %252e%252e%252f becomes ../ at the second stage and walks past a path-traversal check. Decode once, then validate the result.
Security notes: redirects and injection
Encoding is not a security boundary by itself, but forgetting it opens doors. A ?next= parameter holding a full URL should be encoded, and then, importantly, validated against an allow-list on the server; otherwise it is an open redirect that attackers use for phishing. Unencoded & and # in user input allow parameter injection, as shown earlier. Output context matters too: a URL placed inside HTML needs HTML escaping on top (& becomes & in an attribute; see the HTML Entity Encoder), and percent-encoding is a different thing from Base64, which is covered in Base64 is not encryption.
- Encode each value once, with the right function for its position.
- Encode a literal
+as%2B, and a literal%as%25. - Prefer
URL/URLSearchParamsor your language's query builder over concatenation. - Always encode as UTF-8 and say so; do not rely on legacy charsets.
- Validate redirect targets after decoding, not before.
When a request misbehaves, the quickest check is to paste the suspicious URL into the URL Encoder in decode mode, or replay it with the cURL Builder and compare. For what a server does with a malformed request, see HTTP status codes explained: a bad encoding most often earns a 400.