The Schema Was Valid. The Translation Was in Chinese

The useful part

You declare the fields, the server enforces the grammar, and what comes back parses every time. Here's the list of things that came back schema-valid and wrong, in the order I found them. The array was the right shape and the wrong length The model processes several items per call and returns one object per item.

How it works

• What made this worth catching rather than shrugging at is what silence would have cost — a dropped item doesn't come back around on the next pass, because the next pass selects a fresh top slice of new work.
• The fix is boring and unavoidable: reconcile the response against the request by id.
• Send ids in, require ids back, diff the sets, and re-ask individually for whatever went missing.
• "Probably fine, it'll get picked up later" is only true if something actually picks it up later.
• The same reconciliation gives you a free failure mode for the whole batch: if the entire call times out, retry the items one at a time instead of losing all of them to one pathological input.

What to take from it

The field was a string, and it was the wrong language Each item comes back with a translations object: one key per target language, each holding a title and summary.

Details worth keeping

After months of regex-scraping JSON out of prose, it's a genuine relief. Then you ship it, and you find out what a schema actually promises. Everything you care about is content, and content is on you.