Errors
validation_header_invalid
400 — a required request header is missing, malformed, or carries a value outside the allowed set.
Last updated
Cause
Matter requires several headers on every request — Authorization, Matter-Version, and Idempotency-Key on mutating verbs — and individual operations declare additional headers (for example, Matter-Mode for cross-mode reads). validation_header_invalid fires when one of these is present but malformed, or when a required header is absent.
Common triggers are pinned API versions that have been retired (the Matter-Version header must name an active version date), Idempotency-Key values that are not valid UUIDs, content-type headers that don't match the body, or values that include disallowed characters (newlines, control characters, header smuggling attempts).
Fix
- Read the
detailfield on the problem response. It names the offending header and the reason it was rejected. - For
Matter-Version, pin to a published version date. The current and supported versions are listed at/api/api-versions. - For
Idempotency-Key, generate a fresh UUID v4 per logical operation. Never reuse a key across different bodies. - For other headers, the spec for the operation lists the required values and formats. Use the spec, not folklore.
Related codes
validation_body_invalid— the headers were fine but the body failed.validation_query_invalid— a query parameter failed.validation_idempotency_key_conflict— theIdempotency-Keyis well-formed but conflicts with a prior request.