## TL;DR

The docs examples used snake_case but the live API returns camelCase, so every field lookup missed and the client saw nulls. Normalize keys on ingest (convert camelCase to snake_case) or regenerate the client from the live schema, not the docs examples.

## Error

```text
client.user_name is null while the raw JSON clearly has userName
```

## Steps

1. Print the raw response body for one call Expected: you see the actual key casing.
2. Add a key-normalization step (camelCase to snake_case) at the client boundary Expected: all fields parse.
3. Or regenerate the models from the live OpenAPI schema Expected: the models match reality.
4. Add a test asserting a known field parses to a non-null value Expected: casing drift gets caught immediately.

## When to use

- Parsed fields are null but the raw response has data
- Docs examples and the live API disagree on casing

## When not to use

- The API truly returns snake_case (then the bug is elsewhere)
- Field names differ beyond casing

## Tool compatibility

- JSON key normalization
- Generated API models

## Variant phrasings

### api returns null for all fields

Check key casing. Docs said snake_case, live API sends camelCase.

### parsed response is empty but raw json has data

Same: normalize key casing at the boundary.

## Why it happens

Docs examples are often hand-written and drift from the serializer's actual output. Agents trust the examples because they are the most readable part of the docs.

## Edge cases

- Some APIs mix casings across endpoints; normalize per-endpoint if needed
- Normalization must not collide two distinct keys into one

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YKGFvjEpL-FC3T0oNh3Log