agent trusted the spec's required list - the real required fields were only in the docs' prose, and calls 422d

TL;DR

Read the docs' prose for the endpoint, add the prose-required fields to your requests, and the 422s stop. The spec's required list is incomplete; the real requirements are buried in a paragraph the generator never read.

Build a habit of diffing spec-required against prose-required for every endpoint you generate a client for: the spec is machine-readable, the prose is where the truth hides.

Verbatim query

agent trusted the spec's required list  -  the real required fields were only in the docs' prose, and calls 422d

Steps

1. Read the 422 body for the missing field Run the failing call and read the 422 response - it usually names the missing field. Check the spec's required list for that endpoint: the field is likely absent or marked optional. Expected: The 422 names a field the spec did not require.

2. Find it in the docs' prose Read the endpoint's docs page top to bottom, especially notes, callouts, and examples. Highlight every field the prose calls required, mandatory, or always include. Expected: You have a prose-required list that differs from the spec's list.

3. Add the missing fields to the client Update the generated request builder to always send the prose-required fields. If the generator supports required overrides, add them there so regens keep the fix. Expected: Requests now include every prose-required field.

4. Verify each 422 is gone Re-run the failing calls and confirm 2xx. Test with minimal payloads to make sure no other prose-only requirement is hiding. Expected: All previously failing calls succeed with minimal payloads.

5. Record the diff for the next regen Keep a per-endpoint note of prose-required fields the spec misses. Apply it automatically after each regeneration. Expected: A regen does not silently reintroduce the 422s.

Use this when

• Calls 422 on a field the spec marks optional or omits
• The docs page says a field is required in a paragraph but the spec does not
• Generated request builders produce minimal payloads that the live API rejects

Not for this skill when

• The spec's required list already includes the field - the client just is not sending it
• The 422 is about the field's value format, not its presence
• The docs prose and the spec agree - the bug is in your payload, not the requirements

Variant phrasings

required fields only in docs prose

Spec authors update the schema and forget the prose, or write the prose and forget the schema; either way one of them lies.

spec required list incomplete

Machine-readable required lists are only as complete as the last person who edited the spec.

422 on undocumented required field

When the error names a field you never knew was required, the docs prose is the first place to look.

Why it happens

Specs and prose are written by different people at different times. The engineer writes the spec from the validator code; the tech writer writes the prose from the product requirements. When the validator gains a new required field, one of them updates their artifact and the other does not. Generators only read the spec, so they inherit whichever artifact is stale - and the 422 tells you the validator agrees with the prose.

Edge cases

• Some prose requirements are conditional - required only when another field is set - so encode the condition, not just the field
• Examples in the prose often show the real required set better than either list; treat a working example as ground truth
• If the provider has an API changelog, cross-check: new required fields usually appear there first

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yxt4o4bd2isVi1N4YN-Avw