## TL;DR
API updates move fields quietly: a flat score becomes nested under a components object, a field renames, a number becomes a string. The agent should parse defensively (read both old and new paths during transition), validate the payload against a recorded schema, and fail with the payload's actual shape in the log so the next update is a five-minute fix.

```text
agent failed to parse the health score JSON: nested fields missing after API update
```

## Use this when
- Parse errors began at an API release
- The API returns 200 with a changed body shape
- Missing-field or type errors dominate the logs

## Not for this skill when
- The API returns error bodies the agent mistakes for data
- The agent's own request parameters changed the response format

## Steps
1. Capture a full raw response from the updated API and diff it against a pre-update sample. Verify: every moved, renamed, or retyped field is listed
2. Update the parser to the new shape, reading legacy paths as fallback during the transition. Verify: the current payload parses and scores flow again
3. Add a schema validation step that logs the received shape on mismatch instead of a bare parse error. Verify: the next breaking change announces its own diff
4. Pin the API version in requests if the provider supports versioning, and subscribe to its changelog. Verify: future updates become scheduled work, not surprises
5. Add contract tests with recorded payloads for each supported API version. Verify: parser changes are tested against real shapes in CI

## Variant phrasings
### health score JSON parse failed after API update
A related phrasing for the same underlying problem.
### nested fields moved in response
A related phrasing for the same underlying problem.
### API schema change broke agent
A related phrasing for the same underlying problem.

Compatibility: Compatibility: REST JSON APIs consumed by agents (health scoring, CRM, analytics APIs) with versioned or unversioned payloads, current versions.

## Why it happens
Parsers written against one observed payload are bets that the payload never changes. Defensive reading plus shape-logging converts an outage into a diff, and version pinning converts surprise diffs into planned migrations.

## Edge cases / pitfalls
- Numbers arriving as strings are the most common silent retype; coerce explicitly and log coercions during transition.
- Fallback to legacy paths must expire. Leave a dated removal task or the parser becomes archaeology.
- Recorded payloads for tests must be scrubbed of customer data before entering the repo.

## Provenance

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