Refactor error handling and logging in API responses

lib/errors.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * Map internal exceptions to safe, identifiable API error messages (details go to error_log).
+ */
+function qdb_public_error_message(Throwable $e, string $contextLabel = 'Operation'): string
+{
+    $msg = $e->getMessage();
+
+    if (str_contains($msg, 'Could not acquire lock') || str_contains($msg, 'Could not open lock')) {
+        return 'Database is busy. Please try again in a moment.';
+    }
+    if (str_contains($msg, 'decrypt') || str_contains($msg, 'QDB_MASTER_KEY')) {
+        return 'Database configuration error. Contact the server administrator.';
+    }
+    if (str_contains($msg, 'Could not read') || str_contains($msg, 'Could not write')
+        || str_contains($msg, 'Could not save')) {
+        return 'Database storage error. Contact the server administrator.';
+    }
+    if ($e instanceof PDOException) {
+        return $contextLabel . ' failed due to a database error.';
+    }
+
+    return $contextLabel . ' failed. If this persists, contact support.';
+}