URL encoding: a practical guide for query strings and paths

A URI contains components such as a scheme, host, path, query and fragment. Characters that act as separators in one component may be ordinary data in another. Percent-encoding represents a byte as a percent sign followed by two hexadecimal digits, but the decision to encode a character depends on where that value will be placed.

Encode the individual parameter or path segment before assembling the full URL. Encoding the entire URL can transform its colon, slashes, question mark and ampersands, destroying the structure the server needs to interpret the request.

value: north & west
encoded value: north%20%26%20west
query: ?region=north%20%26%20west

In application/x-www-form-urlencoded form data, a plus sign is commonly interpreted as a space and a literal plus is encoded as %2B. In a generic URI component, plus may remain a literal plus. Confusing the two conventions is a frequent cause of broken email aliases, timestamps and signed parameters.

Use the encoder supplied by the API client or framework for the exact component you are building. Avoid hand-written global replacements, because they rarely handle Unicode, existing escape sequences and component boundaries correctly.

If the percent sign in %2F is encoded again, the result becomes %252F. One layer of decoding produces %2F; a second produces a slash. Systems that normalize at different stages can disagree about the resource or path being requested. This can affect routing, cache keys, allowlists and security controls.

Decode only at the layer responsible for interpreting that component, and reject malformed escape sequences. During troubleshooting, record both the exact wire representation and the decoded interpretation without placing secrets into the ticket or browser address bar.

• Do not repeatedly decode until the value stops changing.
• Avoid putting tokens and personal data in query strings.
• Compare the client-generated request with server-side logs using redacted values.
• Preserve case and Unicode normalization when signatures depend on exact bytes.

First separate the URL into components. Identify which component contains the unexpected value, then compare the unencoded data, the encoded component and the final assembled URL. Confirm which specification or framework convention applies, especially for HTML form bodies.

If a signed URL fails, do not edit it experimentally. Recreate the canonical input using the signing implementation's documented rules and a synthetic value. A visually equivalent URL may have a different byte representation and therefore a different signature.