Instruction file imported from code-kern-ai/refinery-gateway (.cursor/rules/exceptions.mdc). Copyright stays with the author.

Exceptions Guidelines

Exception Locations

Gateway exceptions (exceptions/exceptions.py):

• MissingArgumentsException, ProjectAccessError, ServiceRequestsError
• DatabaseSessionError, AuthManagerError, EmbeddingConnectorError

Submodule exceptions:

from submodules.model.exceptions import EntityNotFoundException, EntityAlreadyExistsException

Usage Patterns

Raising exceptions:

# 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:

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