URL Encoding: %20 vs + for Spaces and Why Query Strings Break
Why do some URLs encode spaces as %20 while forms use +? Here is why mixing them breaks API query strings and how to encode URLs correctly.
Have you ever built an API call with a search term, only to find that searching for C++ returns C with missing plus signs, or searching for a file name like report 2026.pdf fails with a 404 error?
The culprit is the battle between %20 and +.
The quick rule is: use %20 for spaces anywhere in a modern URL path or REST API query. Only use + when submitting legacy HTML form data.
You can test and encode URL parameters instantly with our client-side URL encoder decoder.
Here is why both standards exist and why mixing them breaks modern web APIs.
The two conflicting standards
The confusion comes from two different specifications written for two different jobs:
1. The URI Standard (RFC 3986)
This standard defines how all URLs, URIs, and REST paths work across the internet.
Under RFC 3986, spaces are unsafe characters. They must be percent-encoded using their hexadecimal ASCII value: space (ASCII 32, hex 0x20) becomes %20.
Crucially, in RFC 3986, the plus character (+) is a reserved sub-delimiter. It has its own meaning. A literal plus in a URL path or query parameter must be encoded as %2B.
2. The HTML Form Standard (application/x-www-form-urlencoded)
In the early days of the web, the W3C defined how web forms send data via HTTP POST requests.
Because text fields frequently contain multiple words, replacing every space with three characters (%20) inflated payload sizes on slow dial-up connections. The form specification chose a shorthand: replace spaces with +, and encode literal plus signs as %2B.
Standard URI (RFC 3986): /search?q=hello%20world
Form Encoded (application/x-www...): /search?q=hello+world
Where things break in modern APIs
Bugs happen when backend servers parse query strings with the wrong parser.
Problem 1: Searching for literal plus signs
If a user searches for C++ and your frontend uses form encoding, it sends q=C++.
The receiving backend treats those plus signs as spaces, decoding the string into C.
To preserve the plus signs, the frontend must percent-encode them: q=C%2B%2B.
Problem 2: Spaces in URL path segments
In a query string (after the ?), many backends accept + as a space for backward compatibility.
In a URL path segment (before the ?), + is never a space. It is always a literal plus sign.
# Path segment: Points to a file named "my+invoice.pdf"
https://example.com/files/my+invoice.pdf
# Path segment: Points to a file named "my invoice.pdf"
https://example.com/files/my%20invoice.pdf
If your file is named my invoice.pdf and your code generates files/my+invoice.pdf, the web server looks on disk for a file with a literal plus sign in its name, fails to find it, and throws a 404 Not Found.
How to encode URLs safely in code
Avoid generic search-and-replace functions. Use your language’s standard URI encoder:
// In JavaScript:
// encodeURIComponent encodes spaces as %20 and plus signs as %2B
const query = "C++ guide";
const url = `https://api.example.com/search?q=${encodeURIComponent(query)}`;
// Output: https://api.example.com/search?q=C%2B%2B%20guide
# In Python:
import urllib.parse
# quote uses %20 for spaces (RFC 3986 safe for paths and APIs)
urllib.parse.quote("my invoice.pdf") # 'my%20invoice.pdf'
# quote_plus uses + for spaces (only for legacy form bodies)
urllib.parse.quote_plus("my invoice.pdf") # 'my+invoice.pdf'
If you are debugging API responses, payload bodies, or webhook URLs, use the ToolQuilt URL encoder decoder to see how your strings decode under both standards.