Hi Apple team and community,
We’re currently integrating with the Apps and Books for Organizations API as part of our device management solution and would like to highlight a few critical points we've encountered — including a reliability issue, an enhancement suggestion, and a request for clarification on API rate limits.
1. Issue: Intermittent 403 Errors with stoken-authenticated-apps Endpoint
We are encountering intermittent 403 Forbidden responses from the stoken-authenticated-apps endpoint.
Approximately 30–35% of the requests fail with a 403 status code.
These failures are inconsistent — the same request (using the same Content Token and Storefront) may succeed upon retry.
All requests are properly authenticated and include the required Cookie and other headers as specified in the API documentation.
This issue is impacting our ability to reliably fetch app metadata at scale, particularly in workflows.
We’d like to know:
Is this a known issue?
Could it be due to a rate limit or token misconfiguration?
Are any changes required on our end to avoid these failures?
2. Enhancement Request: Include externalVersionId in versionHistory Response
The versionHistory extension currently returns:
versionString
releaseNotes
releaseDate
However, for Declarative Device Management (DDM) workflows such as App Pinning, we need the externalVersionId as well. Without it, we can't reliably correlate version metadata with the specific version ID required for pinning.
Adding externalVersionId would:
Enable precise version targeting during App Pinning
Improve reliability and automation in managed deployments
We request that Apple consider including externalVersionId in the versionHistory response to better support DDM-based app lifecycle management.
3. Rate Limit Clarification
We found the following note in the Apps and Books for Organizations API documentation:
"The Apps and Books for Organizations API limits the number of requests your app can make using a developer token within a specific period of time. If you exceed this limit, you’ll temporarily receive 429 Too Many Requests error responses for requests that use the token. This error resolves itself shortly after the request rate has reduced."
While this confirms that a rate limit is enforced, there is no detailed information about the thresholds — such as the number of allowed requests per minute, hour, or day per developer token.
To help us implement proper throttling and retry strategies, we request clarification on the following:
What is the exact rate limit threshold per developer token?
Are there per-endpoint limits, or is it a global cap for all requests using the token?
Does the API return a Retry-After header when the limit is exceeded?
What is the recommended backoff strategy for clients to follow when receiving 429 errors?
This information would help us implement efficient throttling and error handling logic.
Any insights from the Apple team or other developers who’ve encountered these issues would be greatly appreciated!