Docs: Document Structured Error Handling (Rich Bubbling) in V3 Guide

documentation/V3_FRONTEND_API_GUIDE.md

@@ -261,28 +261,86 @@ The backend is now "Vision Aware." You can send string IDs back to the API using
 
 ## 8. Standard Patterns & Common Pitfalls (2026 Update)
 
+### A. Permissive Update Mode (Available)
 
+**Usage:** High-performance state syncing.
 
-### A. Permissive Update Mode (Upcoming)
+To simplify frontend state management, V3 supports a **Permissive Update Mode**. When enabled, the backend will **ignore** extra fields in your `PATCH` or `POST` payload (like `_processed_at`, `created_on`, or UI-specific keys) instead of returning a `400 Bad Request`.
-
-**Status:** In Development.
-
-
-
-To simplify frontend state management, V3 is introducing a **Permissive Update Mode**. When enabled, the backend will **ignore** extra fields in your `PATCH` payload (like `_processed_at` or `created_on`) instead of returning a `400 Bad Request`.
-
-
 
 - **Header:** `x-ae-ignore-extra-fields: true`
 
+**When to use:**
+- When sending back an object fetched via `GET` that contains read-only technical metadata.
+- When the frontend adds temporary "state" keys to objects that shouldn't be saved to the DB.
 
-
+---
-This allows you to send back larger chunks of the object without meticulously whitelisting every field, though whitelisting remains a best practice for performance.
-
-
 
 ### B. Handle 'NULL' vs '0' for Booleans
 
+
+
 **Pitfall:** Fields like `hide` or `priority` can be `NULL` in the database.
 
-**Standard:** Ensure your synchronization logic in components handles `null`, `undefined`, and `0` identically for boolean checks to prevent "ghost" changes being detected by Svelte 5.
+
+
+**Standard:** Ensure your synchronization logic in components handles `null`, `undefined`, and `0` identically for boolean checks to prevent "ghost" changes being detected by Svelte 5.
+
+
+
+---
+
+
+
+### C. Structured Error Handling (Rich Bubbling)
+
+
+
+V3 provides machine-readable error objects in the `meta.details` field for most failures (400/500). Instead of parsing strings, your error handler should check the `category` and `code`.
+
+
+
+**Example Error Response:**
+
+```json
+
+{
+
+  "meta": {
+
+    "success": false,
+
+    "status_code": 400,
+
+    "status_message": "Failed to update object.",
+
+    "details": {
+
+      "category": "database_schema",
+
+      "code": 1054,
+
+      "message": "Unknown column 'unauthorized_field' in 'SET'",
+
+      "recoverable": false
+
+    }
+
+  }
+
+}
+
+```
+
+
+
+**Common Categories:**
+
+- **`database_duplicate`**: Attempted to create a record with a non-unique value (Code 1062).
+
+- **`database_constraint`**: Foreign key or integrity violation (Codes 1451, 1452).
+
+- **`database_schema`**: Invalid column name or table configuration (Codes 1054, 1146).
+
+- **`database_connection`**: Temporary DB unavailability (`recoverable: true`).
+
+- **`validation`**: Pydantic validation failed (Check `details` for field-specific errors).