Skip to main content
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:
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

Common platform error codes

Current rate limits

These limits reflect the current implementation as of July 28, 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. Bulk sync endpoints accept up to 512 KiB, because a 100-item batch can exceed the ordinary ceiling.

Every authenticated request

Two buckets apply to every request that carries a bearer token. The endpoint-specific limits below apply on top of these, so the tighter of the two is what you will hit first.

Rate limit headers

Every platform response reports the bucket closest to being exhausted:
X-RateLimit-Reset is Unix time in seconds. All three are listed in Access-Control-Expose-Headers, so browser clients can read them on cross-origin requests. Throttle on X-RateLimit-Remaining rather than waiting for a 429. Because the reported bucket is whichever is closest to empty, honouring it keeps you inside both the per-token and per-app ceilings without tracking them separately.

Platform API

Public API

Retry behavior

Every 429 includes a Retry-After header in seconds. Respect that value when retrying; a retry that ignores it consumes budget you have not yet earned back.
  • Retry 429 responses after Retry-After, and throttle on X-RateLimit-Remaining so you rarely reach one.
  • On 409 request_in_progress, wait and retry the same Idempotency-Key.
  • On 409 idempotency_indeterminate, do not reuse the key. That write may or may not have applied; reconcile through GET /api/platform/v1/me/sync/changes and retry with a new key.
  • 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.