App Store Connect reviews API errors and what actually causes them

Any of: no token, a malformed token, the wrong kid, the wrong iss, the wrong aud, the wrong signing algorithm, or an exp more than 20 minutes out. Apple returns a byte-identical body for all of them, so the message tells you nothing about which one it is.

Check the shape before you debug anything else. Header: alg ES256, kid set to your Key ID, typ JWT. Payload for a team key: iss is the Issuer ID, aud is appstoreconnect-v1, plus iat and exp. An individual key is different: it uses sub set to "user" and carries no iss at all, which is the mistake that eats the most time. Send it as Authorization: Bearer.

The token lifetime rule. Apple computes it as exp minus iat, so minting a token with a comfortable expiry is exactly the wrong instinct here.

Re-sign on a schedule rather than reusing one token for a batch run. Long-lived tokens up to six months exist, but only when the token declares a scope and that scope contains only GET requests.

The scope entries do not match the request you are making. It is an allowlist, not a hint.

Match the entry to the request exactly, or drop the scope claim until the rest works. One quirk worth knowing: Apple ignores limit, cursor and sort when it checks the scope, so those three cannot be the mismatch.

The per-hour ceiling on your API key, over a rolling hour.

Read the X-Rate-Limit header, which is on every response and not only on the 429. It looks like user-hour-lim:3500;user-hour-rem:500; so you can throttle before you get rejected rather than after. Limits are per key, so splitting work across keys splits the budget.

Usually nothing is wrong. Publication is asynchronous and Apple documents a delay. There has also been at least one Apple-side outage, reported in November 2025, where the same symptom showed up through the App Store Connect web UI as well, meaning it was not an API-client problem at all. That one was later reported as fixed.

Poll the response state rather than assuming 201 means live. It reads PENDING_PUBLISH until it reads PUBLISHED. If the web UI also loses the reply, it is not your code, and there is no client-side fix.

An Apple staff answer on the developer forums from July 2021. It was true when it was written.

Ignore it. customerReviews and customerReviewResponses shipped in App Store Connect API 2.0, announced at WWDC22. Any answer on this question dated 2021 or earlier is describing a world that no longer exists, and this one still surfaces because it carries an Apple staff badge.

They are different datasets. A rating with no written text is not a review, and the API resource covers reviews customers write.

Use App Store Connect reporting for rating counts, and treat the two numbers as unrelated. There is no documented ratings endpoint.

Undocumented per-client throttling. The feed signals it by returning a well-formed but entry-less success. No 429, no error code, nothing in the headers.

Back off and retry rather than assuming the app has no reviews. Validate the entry count, never the status code. A nonexistent app id also returns 200 with an empty feed, as does omitting or mangling the sortBy path segment, so a typo looks identical to a throttle.

They are not in it. Responses are available only through the authenticated API.

If you need to know whether a review already has a reply, you need App Store Connect API credentials. There is no public route to that field. Worth noting that the equivalent Google Play data is public, which is why cross-store tooling tends to be asymmetric.