## TL;DR

Loosen the generated enum so unknown strings are accepted instead of throwing, and the crashes stop. The API added a new status value the docs do not list yet; a strict enum turns that into a runtime exception.

Log every unknown value you see so you can map it to real handling later, and add the new value to your enum explicitly once the docs confirm what it means.

## Verbatim query

```text
agent trusted the docs' enum values  -  the API added a new status string and the generated client's strict enum threw at runtime
```

## Steps

1. Find where the throw happens
   Read the stack trace and find the generated enum deserialization code - usually a parse or valueOf helper.
   Note the exact new string value the API returned.
   Expected: You can point to the line that throws and the string value that triggered it.

2. Make the enum tolerant of unknowns
   Add a fallback member like UNKNOWN that accepts any unrecognized string instead of throwing.
   Keep the known members as-is so existing comparisons still work.
   Expected: Deserializing the new status string no longer throws; it lands on the fallback member.

3. Log unknown values
   Emit a warning with the raw string whenever the fallback member is used.
   Send that log to whatever you watch, not a file nobody reads.
   Expected: Each new unknown value shows up in your logs with its exact string.

4. Re-run the failing flow end to end
   Replay the payloads that crashed and confirm the client completes the flow.
   Confirm downstream code handles the fallback member sanely.
   Expected: The flow completes with no exceptions; unknown statuses are visible in logs.

5. Update the enum once the docs catch up
   When the provider documents the new value, add it as a real member with handling.
   Remove the fallback only if the docs promise a closed set - they usually do not.
   Expected: The enum lists the new value explicitly; the fallback remains as insurance.

## Use this when

- Your generated client throws on a status string that is not in the docs' enum list
- A previously fine integration starts crashing after the provider ships a new state
- Deserialization errors name a value that looks like a legitimate new status

## Not for this skill when

- The invalid value is one YOUR client sends - that is a payload bug on your side
- The throw happens on values the docs do list - the enum mapping itself is wrong
- The crash is a network or auth error wearing enum clothing - check the trace first

## Variant phrasings

### API returns new enum value not in docs
Providers add states like pending_review or archived without telling anyone first; strict enums are the first casualty.

### strict enum throws on unknown status
If your client validates enums strictly, every new API value is a production crash waiting for the provider's next deploy.

### new status string crashes client
Same failure family: any string field the client treats as a closed set will break when the API grows.

## Why it happens

Enum lists in docs are snapshots, not contracts. Providers add new statuses as their product evolves, and the docs lag by weeks. A generated client that treats the enum as exhaustive turns the next new value into a runtime exception. Tolerant enums plus logging keep the integration running while you decide what the new value means.

## Edge cases

- Some new values carry different business meaning, not just a new label - do not auto-map unknown to success without reading the docs
- If downstream code switches on every enum member, add the fallback branch there too or it will throw again one layer down
- Serialization libraries differ: some throw, some return null - audit the generated parse path, not just the enum definition

## Provenance

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