The Shape Around the Data

The records are almost never at the top level. Responses are usually wrapped: results, docs, items, data, records. Somewhere alongside them is a count, and often paging information.

The wrapper is where you find out how much there is and how to get the rest, so read it before reaching straight for the array.

Counts are frequently approximate. A total or numFound is often an estimate, especially on search endpoints. It can disagree with the number of records you actually receive.

Do not assert that you collected exactly what the API claimed. If they differ, report both. That difference is information about the source, not a failure of your code.