generated TypeScript types said a field was required - the live API omits it half the time and the client threw at...

TL;DR

Mark the field optional in the generated types and guard every access with a fallback, and the crashes stop. The spec says required, but the live API omits the field whenever it has no value.

Sample the real API before trusting required markers: hit the endpoint a few dozen times and check which fields actually show up every time.

Verbatim query

generated TypeScript types said a field was required  -  the live API omits it half the time and the client threw at runtime

Steps

1. Reproduce the crash on a real response

Log a full live response that triggers the throw and find the missing field. Confirm the field is absent, not just null - absent and null are different. Expected: You have a real response missing the field and a stack trace at the access point.

1. Measure how often it is omitted

Collect 30 to 50 live responses and count how many include the field. Check whether the omission correlates with a state, like a new vs archived record. Expected: You know the omission rate and whether it is random or state-dependent.

1. Mark it optional in the types

Change the field to optional in the generated interface and in any hand-written wrappers. If you regenerate often, put the override in a patch file the regen applies. Expected: The type no longer claims the field is always present.

1. Guard every access site

Search for every place the field is read and add a fallback or a check. Prefer default values over non-null assertions. Expected: No read of the field can throw when it is absent.

1. Add a fuzz-style response test

Feed the client recorded real responses, including ones missing the field. Run this on every regen so a reverted type is caught. Expected: The client handles field-absent responses without throwing.

Use this when

• The client throws on a field the spec marks required but live responses omit
• Crashes happen on some records but not others for the same endpoint
• Optional-in-practice fields appear after the API added a new record state

Not for this skill when

• Your code fails to send a field the API requires - that is a request bug, not a response type bug
• The field is present but the wrong type - that is a type-mapping problem
• The throw is on a field that is always present - the access bug is elsewhere

Variant phrasings

API omits field marked required

Required in the spec means required in the author's imagination; the live API decides what actually shows up.

optional field typed as required

One wrong required marker turns a normal API response into a production crash.

client throws on missing optional field

If the field can be absent, the type must say so and every access must handle it.

Why it happens

Spec authors mark fields required based on the happy path: the field exists on a complete record, so they call it required. The API omits it on incomplete, new, or archived records - a different code path the author never tested. The generated types encode the happy path as law, and the first incomplete record throws. Real responses are the only reliable schema.

Edge cases

• Null vs absent matters: some APIs send explicit null, others omit the key - handle both, not just the one you saw
• Nested objects have the same problem one level down; audit the whole interface, not just the field that threw
• If the provider ever starts always sending it, your optional type still works - optional is the safe direction

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_QDP5-a5758dPtqygknrOYg