URL Encoding and Percent-Encoding Guide

URL encoding looks simple until a callback URL, search query, or signed API request breaks in production. The browser accepts many characters that are not safe in every part of a URL, while servers and proxies may normalize the same string differently. A single missing percent sign can turn a value into a new query parameter or make an OAuth redirect fail.

This guide explains how percent-encoding works, which URL components need different rules, and how to test encoded values with the URL Encoder and Decoder before you paste them into API clients, analytics links, or redirect settings.

What Percent-Encoding Actually Does

Percent-encoding replaces a byte with a percent sign followed by two hexadecimal digits. The space character, for example, becomes %20. The slash byte becomes %2F, and a literal percent sign becomes %25.

raw text:       spring sale / week 2
encoded text:   spring%20sale%20%2F%20week%202

raw redirect:   https://app.example.com/callback?plan=team&source=ad
encoded value:  https%3A%2F%2Fapp.example.com%2Fcallback%3Fplan%3Dteam%26source%3Dad

Encoding is not encryption. Anyone can decode it. Its job is to preserve structure: the URL parser should know which characters are separators and which characters are data.

Encode by URL Component, Not by the Whole String

The biggest mistake is encoding an entire URL after it has already been assembled. A full URL contains structural characters such as :, /, ?, &, and =. If those are encoded after assembly, the URL stops being a URL and becomes one long string.

// Good: encode each value before joining the query string.
const q = encodeURIComponent("json schema examples");
const next = encodeURIComponent("/docs/start?tab=api");
const url = `/search?q=${q}&next=${next}`;

// Bad: encode the already assembled URL.
encodeURIComponent("/search?q=json schema examples&next=/docs/start?tab=api");

Path segments have different rules from query values. Encoding /docs/api as a path segment gives %2Fdocs%2Fapi, which means one segment containing slashes. Leaving it unencoded means three segments. Both can be correct, but they are not interchangeable.

Query Strings, Forms, and the Plus Sign

Query strings and HTML form bodies often use the application/x-www-form-urlencoded convention, where a space may appear as + instead of %20. That plus sign is a compatibility rule for form encoding, not a universal URL rule.

search term:  "base64 url safe"
query value:  base64%20url%20safe
form value:   base64+url+safe

literal plus sign: C%2B%2B
decoded value:     C++

This is why a literal plus sign must be encoded as %2B when it is data. Otherwise some decoders will turn it into a space and silently change the value.

OAuth Redirect URIs and Nested URLs

Nested URLs are where encoding bugs become expensive. OAuth and SSO flows often put a full redirect URL inside another URL as a parameter. The inner URL must be encoded as a value so its own ? and & characters do not split the outer query string.

https://auth.example.com/authorize
  ?client_id=abc123
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &state=checkout%3Ateam%3Aannual

When a provider says the redirect URI does not match, compare the decoded value first, then compare the encoded value. Many failures are caused by double encoding, missing trailing slashes, or query parameters that were accidentally parsed by the outer URL.

A Safe URL Encoding Checklist

• Encode each dynamic path segment and query value before joining the URL.
• Do not encode the protocol, host, and URL separators after the full URL is assembled.
• Treat + carefully: encode a literal plus sign as %2B.
• Decode once while debugging. If the result still contains many percent signs, check for accidental double encoding.
• Keep URL encoding separate from Base64 encoding. Base64 changes binary data into text; URL encoding protects URL syntax.

When in doubt, paste the value into a decoder and inspect the boundary between separators and data. Encoding is boring when it is right, and very visible when it is wrong.

Official References

• WHATWG URL Standard — the living standard browsers follow for URL parsing and serialization.
• RFC 3986 — the URI generic syntax reference behind percent-encoding terminology.
• MDN encodeURIComponent() — browser API behavior and examples for encoding URL components.