notion API 400: body failed validation on properties title

TL;DR

Send the title as an array of rich text objects, not a plain string. Notion's title property expects a list like one object holding the text content, and a bare string fails validation every time. Wrap the string and the 400 goes away.

notion API 400: body failed validation on properties title

Steps

1. Find the properties object your code sends and look at the value under the title key. Expected: you see a plain string where Notion expects an array.
2. Rewrite the title value as an array containing one rich text object with your text inside its text content. Expected: the payload shape matches Notion's title format.
3. Confirm the property key in your payload matches the actual title property name in the database (it is often Name, not title). Expected: the key names line up with the database schema.
4. Re-run the create or update call. Expected: Notion returns the page with a 200 instead of the 400.
5. If other properties fail validation next, apply the same fix pattern: check each property's expected type in the docs. Expected: the whole properties object validates.

Use this when

• Notion returns exactly "body failed validation" pointing at the title property.
• A generated client passes a plain string as the title.
• Page creation worked before a database schema rename.

Not for this skill when

• The API key or integration token is invalid (that 401s before validation).
• The page or database id is wrong (that 404s or 400s on the id, not the title).
• A different property fails validation (fix that property's type instead).

Variant phrasings

• Notion API title property validation failed
• Notion body failed validation properties
• Notion create page 400 title invalid

Why it happens

Notion models page titles as rich text arrays because titles can carry formatting and mentions. Generated clients treat title like any other string field and send a bare string, which the API's validator rejects. The property name mismatch is the runner-up cause: the payload says title while the database's title property is actually named something else.

Edge cases

• An empty rich text array is valid and clears the title; a missing title key on update leaves the title unchanged.
• Rich text objects support annotations and links, but plain text content alone is enough to pass validation.
• Database title properties cannot be renamed to a non-title type; if the schema changed, re-check which property is the title.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_UfcNUVMelOta3UxlzhDACQ