use generic error enums message

Author: makara4code

backend/.claude/settings.local.json

@@ -3,7 +3,9 @@
     "allow": [
       "Bash(mkdir:*)",
       "Bash(python:*)",
-      "Bash(.venv/Scripts/python.exe:*)"
+      "Bash(.venv/Scripts/python.exe:*)",
+      "Bash(cat:*)",
+      "Bash(uv run pytest:*)"
     ]
   }
 }

backend/README.md

@@ -16,13 +16,13 @@ By default, the dependencies are managed with [uv](https://docs.astral.sh/uv/),
 From `./backend/` you can install all the dependencies with:
 
 ```console
-$ uv sync
+uv sync
 ```
 
 Then you can activate the virtual environment with:
 
 ```console
-$ source .venv/bin/activate
+source .venv/bin/activate
 ```
 
 Make sure your editor is using the correct Python virtual environment, with the interpreter at `backend/.venv/bin/python`.
@@ -46,21 +46,21 @@ For example, the directory with the backend code is synchronized in the Docker c
 There is also a command override that runs `fastapi run --reload` instead of the default `fastapi run`. It starts a single server process (instead of multiple, as would be for production) and reloads the process whenever the code changes. Have in mind that if you have a syntax error and save the Python file, it will break and exit, and the container will stop. After that, you can restart the container by fixing the error and running again:
 
 ```console
-$ docker compose watch
+docker compose watch
 ```
 
 There is also a commented out `command` override, you can uncomment it and comment the default one. It makes the backend container run a process that does "nothing", but keeps the container alive. That allows you to get inside your running container and execute commands inside, for example a Python interpreter to test installed dependencies, or start the development server that reloads when it detects changes.
 
 To get inside the container with a `bash` session you can start the stack with:
 
 ```console
-$ docker compose watch
+docker compose watch
 ```
 
 and then in another terminal, `exec` inside the running container:
 
 ```console
-$ docker compose exec backend bash
+docker compose exec backend bash
 ```
 
 You should see an output like:
@@ -74,7 +74,7 @@ that means that you are in a `bash` session inside your container, as a `root` u
 There you can use the `fastapi run --reload` command to run the debug live reloading server.
 
 ```console
-$ fastapi run --reload app/main.py
+fastapi run --reload app/main.py
 ```
 
 ...it will look like:
@@ -94,7 +94,7 @@ Nevertheless, if it doesn't detect a change but a syntax error, it will just sto
 To test the backend run:
 
 ```console
-$ bash ./scripts/test.sh
+bash ./scripts/test.sh
 ```
 
 The tests run with Pytest, modify and add tests to `./backend/tests/`.
@@ -134,55 +134,55 @@ From the `./backend/` directory, you can run Alembic commands using `uv run`:
 * Apply all pending migrations:
 
 ```console
-$ uv run alembic upgrade head
+uv run alembic upgrade head
 ```
 
 * Create a new migration after changing models:
 
 ```console
-$ uv run alembic revision --autogenerate -m "Add column last_name to User model"
+uv run alembic revision --autogenerate -m "Add column last_name to User model"
 ```
 
 * View migration history:
 
 ```console
-$ uv run alembic history
+uv run alembic history
 ```
 
 * Check current database revision:
 
 ```console
-$ uv run alembic current
+uv run alembic current
 ```
 
 * Rollback the last migration:
 
 ```console
-$ uv run alembic downgrade -1
+uv run alembic downgrade -1
 ```
 
 ### Running Migrations with Docker
 
 * Start an interactive session in the backend container:
 
 ```console
-$ docker compose exec backend bash
+docker compose exec backend bash
 ```
 
 * Alembic is already configured to import your SQLModel models from `./backend/app/models.py`.
 
 * After changing a model (for example, adding a column), inside the container, create a revision, e.g.:
 
 ```console
-$ alembic revision --autogenerate -m "Add column last_name to User model"
+alembic revision --autogenerate -m "Add column last_name to User model"
 ```
 
 * Commit to the git repository the files generated in the alembic directory.
 
 * After creating the revision, run the migration in the database (this is what will actually change the database):
 
 ```console
-$ alembic upgrade head
+alembic upgrade head
 ```
 
 If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in:
@@ -194,7 +194,7 @@ SQLModel.metadata.create_all(engine)
 and comment the line in the file `scripts/prestart.sh` that contains:
 
 ```console
-$ alembic upgrade head
+alembic upgrade head
 ```
 
 If you don't want to start with the default models and want to remove them / modify them, from the beginning, without having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`. And then create a first migration as described above.

backend/app/modules/items/routes.py

@@ -1,13 +1,13 @@
 import uuid
 from typing import Any
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, status
 
 from app.modules.items.models import Item
-from app.modules.items.schemas import ItemCreate, ItemPublic, ItemsPublic, ItemUpdate
 from app.modules.items.repository import ItemRepository
+from app.modules.items.schemas import ItemCreate, ItemPublic, ItemsPublic, ItemUpdate
 from app.modules.rbac.deps import PermissionsDep
-from app.modules.shared import Message, SessionDep
+from app.modules.shared import ErrorMessage, Message, SessionDep
 
 router = APIRouter(prefix="/items", tags=["items"])
 
@@ -39,7 +39,9 @@ def read_item(
 
     item = session.get(Item, id)
     if not item:
-        raise HTTPException(status_code=404, detail="Item not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=ErrorMessage.ITEM_NOT_FOUND
+        )
     return item
 
 
@@ -69,7 +71,9 @@ def update_item(
     repository = ItemRepository(session)
     item = repository.get_by_id(id)
     if not item:
-        raise HTTPException(status_code=404, detail="Item not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=ErrorMessage.ITEM_NOT_FOUND
+        )
 
     auth.require_owner(item.owner_id)
     return repository.update(db_item=item, item_in=item_in)
@@ -87,7 +91,9 @@ def delete_item(
     repository = ItemRepository(session)
     item = repository.get_by_id(id)
     if not item:
-        raise HTTPException(status_code=404, detail="Item not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=ErrorMessage.ITEM_NOT_FOUND
+        )
 
     auth.require_owner(item.owner_id)
     repository.delete(item)

backend/app/modules/rbac/deps.py

@@ -3,10 +3,11 @@
 import uuid
 from typing import Annotated
 
-from fastapi import Depends, HTTPException
+from fastapi import Depends, HTTPException, status
 
 from app.modules.rbac.service import UserRoleService
 from app.modules.shared.dependencies import CurrentUser, SessionDep
+from app.modules.shared.errors import ErrorMessage
 from app.modules.users.models import User
 
 
@@ -31,8 +32,8 @@ def check_permission(current_user: CurrentUser, session: SessionDep):
         missing = [p for p in permissions if p not in user_permissions]
         if missing:
             raise HTTPException(
-                status_code=403,
-                detail="Access denied",
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=ErrorMessage.ACCESS_DENIED,
             )
         return current_user
 
@@ -91,8 +92,8 @@ def require(self, *permissions: str) -> None:
         missing = [p for p in permissions if p not in self.permissions]
         if missing:
             raise HTTPException(
-                status_code=403,
-                detail="Access denied",
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=ErrorMessage.ACCESS_DENIED,
             )
 
     def require_any(self, *permissions: str) -> None:
@@ -106,8 +107,8 @@ def require_any(self, *permissions: str) -> None:
         """
         if not self.has_any(*permissions):
             raise HTTPException(
-                status_code=403,
-                detail="Access denied",
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=ErrorMessage.ACCESS_DENIED,
             )
 
     def require_owner(self, owner_id: uuid.UUID) -> None:
@@ -117,7 +118,9 @@ def require_owner(self, owner_id: uuid.UUID) -> None:
         Raises 403 Forbidden if user is not the owner.
         """
         if owner_id != self._user.id:
-            raise HTTPException(status_code=403, detail="Access denied")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN, detail=ErrorMessage.ACCESS_DENIED
+            )
 
     def require_owner_or(self, owner_id: uuid.UUID, permission: str) -> None:
         """
@@ -129,7 +132,9 @@ def require_owner_or(self, owner_id: uuid.UUID, permission: str) -> None:
             auth.require_owner_or(item.owner_id, "items:delete")
         """
         if owner_id != self._user.id and not self.has(permission):
-            raise HTTPException(status_code=403, detail="Access denied")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN, detail=ErrorMessage.ACCESS_DENIED
+            )
 
     @property
     def user(self) -> User:

backend/app/modules/shared/__init__.py

@@ -7,13 +7,15 @@
     get_current_user,
     get_db,
 )
+from app.modules.shared.errors import ErrorMessage
 from app.modules.shared.schemas import Message
 
 # Note: require_permission moved to app.modules.rbac.deps
 # Import directly: from app.modules.rbac.deps import require_permission
 
 __all__ = [
     "CurrentUser",
+    "ErrorMessage",
     "Message",
     "SessionDep",
     "TokenDep",

backend/app/modules/shared/errors.py

@@ -0,0 +1,46 @@
+"""Common error messages used across the application."""
+
+from enum import StrEnum
+
+
+class ErrorMessage(StrEnum):
+    """Enumeration of common error messages for consistent error handling."""
+
+    # Authentication errors (401)
+    NOT_AUTHENTICATED = "Not authenticated"
+    INVALID_CREDENTIALS = "Could not validate credentials"
+    INVALID_TOKEN = "Invalid token"
+    INVALID_TOKEN_TYPE = "Invalid token type"
+    REFRESH_TOKEN_NOT_FOUND = "Refresh token not found"
+    INVALID_REFRESH_TOKEN = "Invalid refresh token"
+    INCORRECT_EMAIL_OR_PASSWORD = "Incorrect email or password"
+
+    # Authorization errors (403)
+    ACCESS_DENIED = "Access denied"
+    NOT_ENOUGH_PRIVILEGES = "The user doesn't have enough privileges"
+    NOT_ENOUGH_PERMISSIONS = "Not enough permissions"
+    INSUFFICIENT_PERMISSIONS = "Insufficient permissions"
+
+    # User errors (400/404)
+    USER_NOT_FOUND = "User not found"
+    USER_INACTIVE = "Inactive user"
+    USER_EMAIL_EXISTS = "The user with this email already exists in the system"
+    USER_NOT_EXISTS = "The user with this email does not exist in the system"
+    INCORRECT_PASSWORD = "Incorrect password"
+    SAME_PASSWORD = "New password cannot be the same as the current one"
+    SUPERUSER_CANNOT_DELETE_SELF = "Super users are not allowed to delete themselves"
+    SUPERUSER_CANNOT_MODIFY_SELF = "Super users cannot modify their own record through admin panel"
+    USERS_CANNOT_MODIFY_OWN_ROLES = "Users cannot modify their own roles through admin panel"
+
+    # Resource errors (404)
+    ITEM_NOT_FOUND = "Item not found"
+    SHORT_URL_NOT_FOUND = "Short URL not found"
+    ROLE_NOT_FOUND = "Role not found"
+    PERMISSION_NOT_FOUND = "Permission not found"
+
+    # Conflict errors (409)
+    ROLE_NAME_EXISTS = "Role with this name already exists"
+    CUSTOM_CODE_TAKEN = "This custom code is already taken. Please choose another one."
+
+    # System errors (400)
+    CANNOT_DELETE_SYSTEM_ROLES = "Cannot delete system roles"

backend/tests/api/routes/test_items.py

@@ -4,6 +4,7 @@
 from sqlmodel import Session
 
 from app.core.config import settings
+from app.modules.shared.errors import ErrorMessage
 from app.modules.users.models import User
 from tests.utils.item import create_random_item
 
@@ -50,7 +51,7 @@ def test_read_item_not_found(
     )
     assert response.status_code == 404
     content = response.json()
-    assert content["detail"] == "Item not found"
+    assert content["detail"] == ErrorMessage.ITEM_NOT_FOUND
 
 
 def test_read_item_not_enough_permissions(
@@ -63,7 +64,7 @@ def test_read_item_not_enough_permissions(
     )
     assert response.status_code == 403
     content = response.json()
-    assert content["detail"] == "Permission 'items:read' required"
+    assert content["detail"] == ErrorMessage.ACCESS_DENIED
 
 
 def test_read_items(
@@ -113,7 +114,7 @@ def test_update_item_not_found(
     )
     assert response.status_code == 404
     content = response.json()
-    assert content["detail"] == "Item not found"
+    assert content["detail"] == ErrorMessage.ITEM_NOT_FOUND
 
 
 def test_update_item_not_enough_permissions(
@@ -128,7 +129,7 @@ def test_update_item_not_enough_permissions(
     )
     assert response.status_code == 403
     content = response.json()
-    assert content["detail"] == "Permission 'items:update' required"
+    assert content["detail"] == ErrorMessage.ACCESS_DENIED
 
 
 def test_delete_item(
@@ -157,7 +158,7 @@ def test_delete_item_not_found(
     )
     assert response.status_code == 404
     content = response.json()
-    assert content["detail"] == "Item not found"
+    assert content["detail"] == ErrorMessage.ITEM_NOT_FOUND
 
 
 def test_delete_item_not_enough_permissions(
@@ -170,4 +171,4 @@ def test_delete_item_not_enough_permissions(
     )
     assert response.status_code == 403
     content = response.json()
-    assert content["detail"] == "Permission 'items:delete' required"
+    assert content["detail"] == ErrorMessage.ACCESS_DENIED