validation_body_invalid

Last updated Jun 14, 2026

Cause

Matter validates every request body against the JSON Schema declared on the operation in the OpenAPI spec. validation_body_invalid fires when the body is syntactically valid JSON but one or more fields disagree with the schema — wrong type, missing required field, value out of range, enum value not in the allowed set, malformed identifier, or unknown property when additionalProperties: false is in effect.

The response is a problem+json envelope with a populated errors[] array. Each entry has path (a JSON Pointer to the offending field), message (a human-readable description), and an optional code for programmatic dispatch. Multiple errors are returned in a single response so the caller can fix them in one round trip rather than retrying once per field.

Fix

1. Inspect the errors[] array on the problem response. Each entry tells you which field failed and why.
2. Fix every error before retrying. Submitting a body that fixes one error and leaves another returns the same status with the remaining issues.
3. If you are surprised by the schema, read the operation's request body shape in the API reference — the spec is the source of truth and the validator is generated from it.
4. For nested objects, the path uses JSON Pointer syntax (/grants/0/amount). Walk the body using the pointer to locate the offending value.

Related codes

• validation_query_invalid — the body parsed but a query parameter failed.
• validation_header_invalid — a required header is missing or malformed.
• validation_idempotency_key_conflict — the body is valid but the Idempotency-Key was reused with a different body.
• op_request_too_large — the body parsed but exceeded the size cap.

API reference

• API reference index — /api-reference
• Idempotency — /api/conventions/idempotency