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

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.

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