Platform error shape
Platform endpoints return machine-readable errors shaped like this:X-PunchPlay-Request-Id in the headers. This
envelope is consistent across native platform handlers, including errors from
the underlying list, history, rating, collection, and profile routes.
Common HTTP status codes
Common platform error codes
Current rate limits
These limits reflect the current implementation as of July 27, 2026. JSON and form request bodies accepted by the Platform API are limited to 64 KiB and must arrive within 10 seconds. A body at exactly 64 KiB is accepted.Platform API
Public API
Retry behavior
When a request is rate limited, the API may include aRetry-After header. Respect that value when retrying.
Recommended client behavior
- Retry
429responses with backoff. - Treat
401bearer-token responses as a signal to refresh or re-authorize. - Treat
403as a permission problem for that token. - Treat
400validation and scope errors as non-retryable until you fix the request. - Treat
408as retryable only when the client can send the complete body promptly. - Reduce the body before retrying a
413response. - Do not retry
invalid_clientuntil you verify app credentials. - Replace refresh tokens immediately when a refresh response returns a new one.
- Log
request_id, endpoint, status code, and raw error body for every failed platform request.
What to send support
If something breaks and you need investigation, send:request_id- UTC timestamp
- endpoint path
- HTTP status code
client_id- raw error body
request_id, so that information is enough to trace the failure quickly.