Paginate, filter, sort and sparse-fieldset App Store Connect API responses while respecting per-key rate limits and parsing error bodies

Documented steps

1. Issue the initial list request with a bounded page size: curl -H 'Authorization: Bearer <token>' "https://api.appstoreconnect.apple.com/v1/apps?limit=200". The documented maximum for limit on /v1/apps is 200.
2. Read meta.paging, e.g. {"paging":{"total":431,"limit":2}}, for the total resource count and effective page size.
3. Read the links object. links.self is the URL that produced this page; links.next is present ONLY when more pages exist and carries an opaque cursor, e.g. ...?cursor=AoJ4g7mg6o4DKzEwNzQ2ODIxOTc2.ANrJC88&limit=2
4. Fetch the next page by GETting links.next verbatim. Never hand-construct cursor values. Stop when a response has no links.next.
5. Narrow results with filter[<attribute>], which accepts comma-separated or repeated values: filter[bundleId]=com.example.app, filter[appStoreVersions.appVersionState]=READY_FOR_REVIEW
6. Sort with the sort param: field name for ascending, leading '-' for descending, e.g. sort=-name. Only the sort fields documented per endpoint are valid (name, bundleId, sku for /v1/apps).
7. Shrink payloads with sparse fieldsets: fields[<resourceType>]=attr1,attr2, e.g. fields[apps]=name,bundleId,sku
8. Expand relationships inline with include=<rel1>,<rel2>, e.g. include=appStoreVersions,builds, and scope the included attributes with a matching fields[<relatedType>] param such as fields[builds]=version,uploadedDate
9. Combine: curl -H 'Authorization: Bearer <token>' "https://api.appstoreconnect.apple.com/v1/apps?filter[bundleId]=com.example.app&sort=-name&fields[apps]=name,bundleId&include=appStoreVersions&limit=50"
10. After every response inspect the X-Rate-Limit header, formatted like user-hour-lim:3500;user-hour-rem:500; — user-hour-lim is the per-key hourly cap and user-hour-rem is requests left in the current rolling hour. Throttle proactively as user-hour-rem approaches zero.
11. Rate limits are enforced per API key over a ROLLING hour, not a fixed clock hour, so spreading calls out genuinely helps.
12. On HTTP 429 (error code RATE_LIMIT_EXCEEDED) stop issuing requests on that key and retry later with exponential backoff or a queue. Immediate retries keep failing until the window frees.
13. On any 4xx/5xx parse the body as an ErrorResponse: {"errors":[{"id":...,"status":"400","code":"PARAMETER_ERROR.INVALID","title":"A parameter has an invalid value","detail":"'emaill' is not a valid filter type","source":{"parameter":"filter[emaill]"}}]}. Use source.parameter or source.pointer to locate exactly what was wrong.
14. Match errors[].code by dot-delimited PREFIX rather than exact string — the codes are hierarchical (PARAMETER_ERROR.INVALID, PARAMETER_ERROR.REQUIRED, ENTITY_ERROR.ATTRIBUTE.INVALID) so one branch can handle a whole family.
15. Official docs: https://developer.apple.com/documentation/appstoreconnectapi/identifying-rate-limits | https://developer.apple.com/documentation/appstoreconnectapi/interpreting-and-handling-errors | https://developer.apple.com/documentation/appstoreconnectapi/parsing-the-error-response-code | https://developer.apple.com/documentation/appstoreconnectapi/about-the-http-status-code