feat: another balance and bug fix pass (#238)

Working through open issues — fixes, balance changes, and features.

## Closed

- Closes #161
- Closes #181
- Closes #191
- Closes #199
- Closes #201
- Closes #202
- Closes #203
- Closes #204
- Closes #205
- Closes #206
- Closes #208
- Closes #211
- Closes #212
- Closes #213
- Closes #214
- Closes #216
- Closes #219
- Closes #220
- Closes #221
- Closes #222
- Closes #224
- Closes #225
- Closes #226
- Closes #228
- Closes #229
- Closes #230
- Closes #231
- Closes #232
- Closes #233
- Closes #234
- Closes #235
- Closes #236

✨ This PR was created with help from Hikari~ 🌸

Reviewed-on: #238
Co-authored-by: Hikari <hikari@nhcarrigan.com>
Co-committed-by: Hikari <hikari@nhcarrigan.com>

apps/web/src/api/client.ts

@@ -38,6 +38,26 @@ import type {
 
 const baseUrl = "/api";
 
+/**
+ * Represents a 4xx API error so callers can distinguish expected server
+ * rejections from unexpected failures. ValidationErrors are downgraded to
+ * console.warn and are not forwarded to the error-email pipeline.
+ */
+class ValidationError extends Error {
+  public readonly statusCode: number;
+
+  /**
+   * Creates a new ValidationError.
+   * @param message - The error message from the server response.
+   * @param statusCode - The HTTP status code (4xx) returned by the server.
+   */
+  public constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "ValidationError";
+    this.statusCode = statusCode;
+  }
+}
+
 const getToken = (): string | null => {
   return globalThis.localStorage.getItem("elysium_token");
 };
@@ -72,6 +92,9 @@ const fetchJson = async <T>(
       = typeof errorBody.error === "string"
         ? errorBody.error
         : "Unknown error";
+    if (response.status >= 400 && response.status < 500) {
+      throw new ValidationError(message, response.status);
+    }
     throw new Error(message);
   }
 
@@ -326,6 +349,7 @@ const updateProfile = async(
 };
 
 export {
+  ValidationError,
   achieveApotheosis,
   buyEchoUpgrade,
   buyPrestigeUpgrade,