validation_query_invalid

Last updated Jun 14, 2026

Cause

Matter validates every query parameter against the parameter schema declared on the operation. validation_query_invalid fires when a query parameter has the wrong type (a non-integer where an integer is required), an out-of-range value (a limit above the maximum, a cursor that doesn't parse), an enum value not in the allowed set, or a required parameter is missing.

Common triggers are clients that URL-encode the wrong way (double-encoded %2520 instead of %20), clients that send empty values for required filters, and pagination cursors that have been hand-edited rather than passed through verbatim from a previous response.

Fix

1. Read the problem response's errors[] array. Each entry names the offending query parameter and why it failed.
2. For pagination, never construct cursors yourself. Use the next and prev cursors returned in list responses verbatim.
3. For filters, confirm the type — integers must be bare digits, booleans must be true or false exactly, ISO timestamps must include the timezone marker.
4. For URL encoding, encode once. Most HTTP clients encode automatically; check that you aren't double-encoding by passing already-encoded strings into a builder.

Related codes

• validation_body_invalid — the query was fine but the body failed.
• validation_header_invalid — a required header is malformed.

API reference

• API reference index — /api-reference
• Pagination — /api/conventions/pagination