Error Handling

All API errors follow a consistent JSON format. The HTTP status code indicates the category of error, and the error code provides specific details.

Error Format

Every error response is JSON whose data.error object holds the code, the message and, for some codes, details:

{
  "statusCode": 400,
  "data": {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The game name is required"
    }
  }
}

Read the code and message from data.error. The web server adds other top-level fields (a top-level error, when present, is only true); do not rely on them. A response that is not JSON, or has no data.error, comes from a proxy in between, not from Playtest Parlor.

HTTP Status Codes

Error Codes

Rate Limits

Two kinds of request are rate limited, and no others. Each limit is counted per Playtest Parlor account: every app acting for the same person, and that person's own use of the site, draw on one allowance.

When you exceed a limit, you receive a 429 response with RATE_LIMITED code. The response includes a Retry-After header (in whole seconds) telling you when to retry, and the same number appears in the body as data.error.details.retryAfterSeconds. The data.error.message also says the wait in words, for example "Upload rate limit exceeded. Try again in 3 seconds."

The value comes from the rate limiter itself, so it is exactly when your next request will be accepted, never an estimate. It is rounded up, so waiting it out always works.

Waiting When Asked To

Two answers ask you to wait and send the same request again: 429 RATE_LIMITED and 503 RETRY_LATER. Both carry a Retry-After header with the seconds to wait, and the same number in data.error.details.retryAfterSeconds.

1. Wait the seconds in data.error.details.retryAfterSeconds (the same number as Retry-After). Waiting longer only slows you down; the server says when it expects to accept the request.
2. Send the same request again.
3. Expect to be asked more than once, and keep going for several minutes before giving up: an upgrade of how imports are stored asks for 2 minutes at a time and can take a few minutes.

Any other 429 or 503, such as a proxy's error page with no API error body, is not one of these and should not be waited out.

A browser script on another site can call the /api/v1/ routes, and can read Retry-After from them: their CORS answer lists it in Access-Control-Expose-Headers. POST /api/assets/cache-external sends no CORS headers, so a browser script on another site cannot call it at all; call it from your server.

Example:

// Sends a request, waiting out RATE_LIMITED and RETRY_LATER for as long as each answer
// asks, up to ten minutes in all. Returns every other answer, or the last refusal once
// waiting longer would pass ten minutes.
async function fetchWithRetry(url, options, maxWaitSeconds = 10 * 60) {
  for (let waited = 0; ; ) {
    const response = await fetch(url, options);
    if (response.status !== 429 && response.status !== 503) return response;
    let error;
    try { error = (await response.clone().json()).data?.error; } catch { /* not JSON */ }
    if (error?.code !== "RATE_LIMITED" && error?.code !== "RETRY_LATER") return response;
    const seconds = error.details.retryAfterSeconds;
    if (waited + seconds > maxWaitSeconds) return response;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    waited += seconds;
  }
}

Common Errors and Solutions

VALIDATION_ERROR on game creation

Error: Missing required field name

Solution: Ensure you include the name field in your request:

{
  "name": "My Game"
}

INVALID_TOKEN on API request

Error: Your token is invalid or expired

Solution:

1. Check that your token is correctly formatted (starts with pp_)
2. Verify you're including it in the Authorization: Bearer header
3. If the user revoked the token in Settings, redirect them to authorize again

RATE_LIMITED on asset upload

Error: Upload rate limit exceeded. Try again in 1 second.

Solution:

1. Wait the number of seconds specified in Retry-After, then send the same request again
2. Upload fewer files at once: 200 uploads can start together, then one every 0.1 seconds
3. Remember the allowance is shared with the person's own uploads on the site and with any other app acting for them

PLAN_LIMIT on creating a game

Error: You can have one game on Starter. To start a new one, upgrade to Casual for $18 per year.

The account already has as many games as its plan allows: one on Starter, 5 on Casual. Pro has no game limit. Nothing already there is deleted.

Solution: Upgrade the plan, then create the game again.

PLAN_LIMIT on asset upload

Error: This upload would not fit the storage it counts against

A file of a game counts against the storage of the game's owner. Each plan has its own storage: 50 MB on Starter, 300 MB on Casual, 20 GB on Pro. The message names the size of the file, how much room is left, and the plan's storage. POST /api/assets/cache-external cannot know an image's size before it fetches it, so it is refused before fetching only once the storage is full, and after fetching when the images it stored do not fit, which are then deleted.

Solution:

1. Upgrade the plan
2. Delete games or assets that are no longer needed
3. Replace large art with smaller exports

FILE_TOO_LARGE on asset upload

Error: A single file is over the 20 MB per-file limit

This is a different problem from PLAN_LIMIT, and it has a different fix: the account has room, this one file is too big. Export the image at a lower resolution and upload it again.

DERIVATION_FAILED on image processing

Error: Image could not be processed

Solution:

1. Verify the image is a valid PNG or JPEG
2. Check that the file is not corrupted
3. Ensure widthPx and heightPx values match the actual image dimensions
4. Try re-uploading the asset