Errors & Rate Limits

This page documents the current developer-facing error behavior for the versioned public and platform APIs.

Platform error shape

Platform endpoints return machine-readable errors shaped like this:

{
  "error": "insufficient_scope",
  "message": "This token is missing the required scope: playback:write.",
  "request_id": "ppreq_1234567890abcdef1234",
  "required_scope": "playback:write"
}

Platform responses also include 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

Status	Meaning
`200`	Request succeeded
`400`	Invalid request body, parameter, scope request, or unresolved device-code state
`401`	Missing, invalid, expired, revoked, or mismatched credentials
`403`	Token does not have access to the requested surface
`408`	Request body was not received within 10 seconds
`404`	Unknown route or missing resource
`413`	Request body exceeded the 64 KiB platform limit
`429`	Too many requests
`500`	Temporary server-side failure

Common platform error codes

Error	Meaning
`authorization_pending`	User has not approved the device code yet
`expired`	Device code is invalid or expired
`first_party_only`	The endpoint is reserved for an official PunchPlay client
`invalid_client`	`client_id` or `client_secret` is invalid
`invalid_grant`	Refresh token or authorization code is invalid, expired, revoked, or already used
`invalid_request`	Required fields are missing or malformed
`invalid_scope`	The request asked for a scope outside the app’s configured `allowed_scopes`
`invalid_token`	The bearer token is not allowed to use the platform API
`insufficient_scope`	The bearer token does not include the scope required by the endpoint
`not_found`	The requested platform resource does not exist
`rate_limited`	The request exceeded a current limit
`server_error`	Temporary server-side failure
`unauthorized_client`	The app is inactive or unknown for the attempted OAuth flow
`unsupported_grant_type`	`grant_type` is not supported
`unsupported_response_type`	`response_type` is not supported

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

Endpoint area	Limit
`POST /api/platform/v1/auth/device/code`	10 requests per hour per IP
`POST /api/platform/v1/auth/device/token`	200 requests per 10 minutes per IP
`POST /api/platform/v1/auth/refresh`	20 requests per hour per IP
`POST /api/platform/v1/oauth/token`	180 admission attempts per minute per IP, then 120 requests per minute per client and IP
`GET /api/platform/v1/calendar`	60 requests per minute per app and user
`GET /api/platform/v1/me/history`	120 requests per minute per app and user
`GET /api/platform/v1/me/lists`	120 requests per minute per app and user
`POST /api/platform/v1/playback/{action}`	120 requests per 5 minutes per user
`GET /api/platform/v1/playback/events`	20 connection attempts per minute per token and 60 per minute per user

Public API

Endpoint area	Limit
`GET /api/public/v1/users/{username}`	60 requests per minute per IP
`GET /api/public/v1/catalog/search`	60 requests per minute per IP
`GET /api/public/v1/catalog/trending`	60 requests per minute per IP
`GET /api/public/v1/catalog/discover`	90 requests per minute per IP
`GET /api/public/v1/community/overview`	60 requests per minute per IP

Retry behavior

When a request is rate limited, the API may include a Retry-After header. Respect that value when retrying.

Recommended client behavior

Retry 429 responses with backoff.
Treat 401 bearer-token responses as a signal to refresh or re-authorize.
Treat 403 as a permission problem for that token.
Treat 400 validation and scope errors as non-retryable until you fix the request.
Treat 408 as retryable only when the client can send the complete body promptly.
Reduce the body before retrying a 413 response.
Do not retry invalid_client until 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

PunchPlay persists request logs keyed by request_id, so that information is enough to trace the failure quickly.

Stability note

The platform contract is versioned, but rate limits may evolve as usage patterns become clearer. If your integration depends on sustained high-volume traffic, design for graceful backoff and batching where possible.

Getting Started

Guides

Reference

Errors & Rate Limits

Platform error shape

Common HTTP status codes

Common platform error codes

Current rate limits

Platform API

Public API

Retry behavior

Recommended client behavior

What to send support

Stability note

​Platform error shape

​Common HTTP status codes

​Common platform error codes

​Current rate limits

​Platform API

​Public API

​Retry behavior

​Recommended client behavior

​What to send support

​Stability note

Platform error shape

Common HTTP status codes

Common platform error codes

Current rate limits

Platform API

Public API

Retry behavior

Recommended client behavior

What to send support

Stability note