Skip to main content
This page documents the current developer-facing error behavior for the stable 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.

​
Common HTTP status codes

StatusMeaning
200Request succeeded
400Invalid request body, parameter, scope request, or unresolved device-code state
401Missing, invalid, expired, revoked, or mismatched credentials
403Token does not have access to the requested surface
404Unknown route or missing resource
429Too many requests
500Temporary server-side failure

​
Common platform error codes

ErrorMeaning
authorization_pendingUser has not approved the device code yet
expiredDevice code is invalid or expired
invalid_clientclient_id or client_secret is invalid
invalid_grantRefresh token or authorization code is invalid, expired, revoked, or already used
invalid_requestRequired fields are missing or malformed
invalid_scopeThe request asked for a scope outside the app’s configured allowed_scopes
invalid_tokenThe bearer token is not allowed to use the platform API
insufficient_scopeThe bearer token does not include the scope required by the endpoint
not_foundThe requested platform resource does not exist
rate_limitedThe request exceeded a current limit
server_errorTemporary server-side failure
unauthorized_clientThe app is inactive or unknown for the attempted OAuth flow
unsupported_grant_typegrant_type is not supported
unsupported_response_typeresponse_type is not supported

​
Current rate limits

These limits reflect the current implementation as of June 9, 2026.

​
Platform API

Endpoint areaLimit
POST /api/platform/v1/auth/device/code10 requests per hour per IP
POST /api/platform/v1/auth/device/token200 requests per 10 minutes per IP
POST /api/platform/v1/auth/refresh20 requests per hour per IP
POST /api/platform/v1/oauth/token120 requests per minute per client and IP
POST /api/platform/v1/playback/{action}120 requests per 5 minutes per user

​
Public API

Endpoint areaLimit
GET /api/public/v1/users/{username}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.
  • 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.
  • Do not retry invalid_client until you verify app credentials.
  • 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
That gives PunchPlay enough context 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.