exceptions.mdc

---
description: Rules for exception handling and custom exceptions
globs: ["exceptions/**/*.py", "**/*.py"]
alwaysApply: true
---

# Exceptions Guidelines

## Exception Locations

**Gateway exceptions** (`exceptions/exceptions.py`):
- `MissingArgumentsException`, `ProjectAccessError`, `ServiceRequestsError`
- `DatabaseSessionError`, `AuthManagerError`, `EmbeddingConnectorError`

**Submodule exceptions**:
```python
from submodules.model.exceptions import EntityNotFoundException, EntityAlreadyExistsException
```

## Usage Patterns

**Raising exceptions:**
```python
# Validation
if not name:
    raise MissingArgumentsException("Project name is required")

# Not found
proj = project.get(project_id)
if not proj:
    raise EntityNotFoundException(f"Project {project_id} not found")

# Business logic
if not has_access(user_id, project_id):
    raise ProjectAccessError(f"User {user_id} does not have access")
```

**Handling in routes:**
```python
try:
    result = manager.operation(project_id)
    return pack_json_result(result)
except EntityNotFoundException as e:
    return pack_json_result({"error": str(e)}, status_code=404)
except ProjectAccessError as e:
    return pack_json_result({"error": str(e)}, status_code=403)
except Exception as e:
    logger.error(f"Error: {e}", exc_info=True)
    return GENERIC_FAILURE_RESPONSE
```

## HTTP Status Code Mapping

- `400`: `ValueError`, `MissingArgumentsException`
- `403`: `ProjectAccessError`
- `404`: `EntityNotFoundException`
- `409`: `EntityAlreadyExistsException`
- `500`: `ServiceRequestsError`, `DatabaseSessionError`

## Best Practices

1. Use specific exception types, not generic `Exception`
2. Provide clear error messages with context
3. Log exceptions before raising or handling
4. Map exceptions to appropriate HTTP status codes
5. Don't swallow exceptions silently