Documents

Error Codes Guide

When the Gameboy app cannot reach the Pokémon API, an error code appears on screen. Use this guide to interpret each code and troubleshoot the issue.

GB-001 — Network or CORS Blocked

The browser could not reach the API endpoint.

Check your internet connection and refresh the page.
Disable VPNs, browser extensions, ad blockers, or strict privacy settings that may block API requests.
Confirm the API base URL is correctly set in the application configuration.

GB-002 — Request Timeout

The API did not respond within the expected time.

Try again after a few seconds.
Check for a slow or unstable network connection.

GB-003 — API Endpoint Not Found

The request did not match any known API route.

Verify the API base URL is pointing to the live Pokémon API.
Confirm the Pokémon API service is deployed, healthy, and the requested route exists.

GB-004 — Rate Limited

Too many requests have been sent to the API in a short period.

The default limit is 3 requests per minute per IP (this value is configurable via environment variable `API_RATE_LIMIT`).
Wait at least one minute before trying again.
Avoid sending multiple requests in rapid succession.

GB-005 — Service Unavailable

The API is unavailable or experiencing server errors (HTTP 5xx).

Wait and try again later.
Check the Pokémon API service status and logs for errors or outages.

Developer Menu (Hidden)

A hidden developer menu is available for intentionally triggering error states and testing error handling.

Unlock Sequence (D-pad):
Press left 4 times, up 2 times, then down 69 times (total: 4 left, 2 up, 69 down; 75 presses).
After unlocking, a "DEV" menu item appears in the main menu. Use A/Start to enter.

Menu actions:

RATE LIMIT: Fires rapid requests with `persist=false` to trigger a 429 (GB-004).
TIMEOUT: Sends a request designed to exceed the timeout limit to trigger GB-002.
NOT FOUND: Requests a non-existent endpoint to trigger GB-003.

Display & Controls

The Gameboy LCD is rendered at its original 160x144 pixel resolution, scaled for modern displays.
Navigation is D-pad/keyboard only; touchscreen input is not supported.