Error Codes

All PlayRen API endpoints return consistent error responses. This page documents every error status code and its meaning.

Error Response Format

All errors follow this JSON structure:

{
  "error": "error_code",
  "message": "A human-readable description of what went wrong."
}

The error field is a machine-readable code (snake_case) that your application can use for programmatic error handling. The message field provides a human-readable explanation.

HTTP Status Codes

400 Bad Request

The request is malformed or missing required fields.

{
  "error": "invalid_request",
  "message": "The 'gameSlug' field is required."
}

Common causes:

• Missing required parameters in the request body.
• Invalid parameter types (e.g., passing a string where a number is expected).
• Malformed JSON in the request body.
• Invalid slug format or out-of-range values.

401 Unauthorized

The request lacks valid authentication credentials.

{
  "error": "unauthorized",
  "message": "You must be logged in to access this resource."
}

Common causes:

• No session cookie provided.
• Session token has expired (tokens expire after 30 days).
• Token is invalid or has been revoked.

Resolution: Re-authenticate by signing in again.

403 Forbidden

The user is authenticated but does not have permission to perform this action.

{
  "error": "forbidden",
  "message": "You do not have access to this game."
}

Common causes:

• Trying to access a game not in your library (no valid library code).
• Trying to access admin endpoints without admin privileges.
• Trying to modify another user's save data or session.
• Partner API key does not have access to the requested resource.

404 Not Found

The requested resource does not exist.

{
  "error": "not_found",
  "message": "Game with slug 'nonexistent-game' not found."
}

Common causes:

• Invalid game slug or session ID.
• The resource was deleted.
• Typo in the URL path.

409 Conflict

The request conflicts with the current state of the server.

{
  "error": "session_active",
  "message": "You already have an active game session. Stop it before launching a new game."
}

Common causes:

• Trying to launch a game while another session is already running.
• Trying to create a save slot when all 3 slots are occupied.
• Trying to create a duplicate resource (e.g., adding a library code that's already linked).

429 Too Many Requests

Rate limit exceeded.

{
  "error": "rate_limited",
  "message": "Too many requests. Please try again in 60 seconds.",
  "retryAfter": 60
}

Rate limits by endpoint:

• Login: 5 attempts per 15 minutes per email.
• Game launch: 10 requests per minute per user.
• General API: 100 requests per minute per user.
• Partner API: 100 requests per minute per API key.

The retryAfter field (in seconds) indicates how long to wait before retrying.

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again later."
}

Common causes:

• Database connection failure.
• Unhandled exception in the API route.
• Pool agent communication failure.

If you encounter persistent 500 errors, check the Status page for known issues or contact support.

502 Bad Gateway

The platform could not communicate with an upstream service.

{
  "error": "upstream_error",
  "message": "Could not reach the game server. Please try again."
}

Common causes:

• Game server's pool agent is down or unreachable.
• Network issue between the platform and the game server.

503 Service Unavailable

The service is temporarily unable to handle the request.

{
  "error": "no_servers",
  "message": "No game servers are currently available. Please try again in a few minutes."
}

Common causes:

• All game servers are at capacity.
• Maintenance is in progress.
• No servers are registered or healthy.

Handling Errors in Your Application

Best practices for handling PlayRen API errors:

1. Always check the status code before parsing the response body.
2. Use the error field for programmatic handling, not the message field (which may change).
3. Implement retry logic for transient errors (429, 500, 502, 503) with exponential backoff.
4. Respect retryAfter headers and fields on 429 responses.
5. Log the full error response for debugging.

Next Steps

• Authentication — Session and token management.
• Games API — Game catalog endpoints.
• Sessions API — Game session management.