2026-07-18 · 5 min read · Rahul Chitturi
- url
- api
- debugging
Array filters in query strings fail quietly because there is no single universal format. One client sends tags=a&tags=b, another sends tags[]=a&tags[]=b, and a third sends tags=a,b. The backend parser may accept only one of those shapes.
Before rewriting the endpoint, compare a working request with a failing request at the raw URL level. Browser devtools, API clients, SDKs, and reverse proxies can each encode spaces, commas, brackets, and repeated keys differently.
Name the contract explicitly
A clear API contract should say how arrays, empty values, booleans, nested filters, and repeated keys are represented. If that contract lives only in one SDK helper, every non-SDK caller has to guess.
- Repeated keys: filter=red&filter=blue
- Bracket notation: filter[]=red&filter[]=blue
- Comma-separated values: filter=red,blue
- JSON encoded values: filter=%5B%22red%22%2C%22blue%22%5D
Check parser boundaries
The bug may be outside the handler. Gateways can normalize duplicate query parameters, analytics middleware can drop empty values, and generated clients can encode arrays differently after a dependency upgrade.
For a safe reproduction, save the raw URL, the parsed query object, and the final database filter side by side. That shows whether the value was lost at encoding, parsing, validation, or query-building time.
A Flashman workflow
Use the URL encoder/decoder to inspect percent encoding, the JSON formatter when filters are embedded as JSON, and the diff tool to compare request examples from docs, SDK output, and production logs.
Finish the fix by adding examples to the versioned docs. Query-string compatibility is easy to break again unless tests cover both the canonical format and any supported legacy format.