URL Encoding Reference for Query Strings, Paths, and API Integrations
A field guide to percent-encoding so you know what to encode, what to leave alone, and where integrations usually break.
Why URL encoding fails in real projects
Most URL bugs are not caused by the algorithm. They are caused by encoding the wrong part of the URL, encoding twice, or signing a value before its final representation is known.
If a redirect target, search term, callback URL, or path segment is broken, the first thing to inspect is whether the right boundary was encoded at the right time.
Encode components, not entire URLs by default
The safest default is to encode the piece you are inserting, not the complete URL string that already contains separators like slash, question mark, ampersand, and equals.
For example, user-provided search text belongs in a query parameter value. That means you encode the value, not the full URL template.
Search term: error logs & alerts
Encoded value: error%20logs%20%26%20alerts
Final URL: https://example.com/search?q=error%20logs%20%26%20alertsCases that commonly break
OAuth callbacks, webhook endpoints, signed CDNs, and deep links all depend on exact byte representation. A single double-encoding step can turn a valid URL into an invalid one or break signature verification.
- Encoding a full callback URL and then encoding it again as a parameter.
- Treating path segments and query values as if they use the same escaping rules.
- Replacing spaces with plus signs in places that expect percent-encoding instead.
- Decoding too early before all parsing and verification is complete.
A practical review checklist
When debugging an integration, isolate each part of the address and ask what data is raw user content versus structural URL syntax.
- Identify whether the value belongs in the path, query, or fragment.
- Encode the inserted component once.
- Log the final assembled URL before transmission.
- If signatures are involved, sign the exact final representation.
When to decode
Decode only when you need the semantic value. If you are still routing, comparing, or validating a URL against a protocol requirement, premature decoding can hide the actual mismatch.
Frequently asked questions
Should spaces become plus signs or percent-20?
That depends on the context. Traditional form encoding often uses plus, while general URL component encoding uses percent-20.
What does double-encoding look like?
A value like %2F becoming %252F is the classic sign. The percent character itself has been encoded a second time.
Can I encode an entire URL safely?
Yes, but only when the whole URL is being treated as a value inside another context, such as a callback parameter.