Add QuotaExceededError and fix STORAGE_LIMIT_EXCEEDED / COLLECTION_LIMIT_EXCEEDED mapping.

Introduce QuotaExceededError, route storage and collection quota codes to it, guard details.get() calls against None.

Author: l-td

aetherfy_vectors/__init__.py

@@ -18,6 +18,7 @@
     SchemaValidationError,
     SchemaNotFoundError,
     CollectionInUseError,
+    QuotaExceededError,
 )
 from .models import (
     SearchResult,
@@ -42,6 +43,7 @@
     "SchemaValidationError",
     "SchemaNotFoundError",
     "CollectionInUseError",
+    "QuotaExceededError",
     "SearchResult",
     "Point",
     "Collection",

aetherfy_vectors/exceptions.py

@@ -137,6 +137,23 @@ def __init__(self, collection_name: str, agents: list, **kwargs):
         self.agents = agents
 
 
+class QuotaExceededError(AetherfyVectorsException):
+    """Tier quota exceeded (e.g. collection count limit)."""
+
+    def __init__(
+        self,
+        message: str,
+        quota_type: str,
+        current: Optional[int] = None,
+        limit: Optional[int] = None,
+        **kwargs,
+    ):
+        super().__init__(message, **kwargs)
+        self.quota_type = quota_type
+        self.current = current
+        self.limit = limit
+
+
 class SchemaNotFoundError(AetherfyVectorsException):
     """No schema defined for collection."""
 

aetherfy_vectors/utils.py

@@ -146,7 +146,21 @@ def parse_error_response(
             message, request_id=request_id, status_code=status_code, details=details
         )
     elif status_code == 429:
-        retry_after = details.get("retry_after")
+        if error_code == "STORAGE_LIMIT_EXCEEDED":
+            from .exceptions import QuotaExceededError
+
+            current = details.get("current") if isinstance(details, dict) else None
+            limit = details.get("limit") if isinstance(details, dict) else None
+            return QuotaExceededError(
+                message,
+                "storage",
+                current=current,
+                limit=limit,
+                request_id=request_id,
+                status_code=status_code,
+                details=details,
+            )
+        retry_after = details.get("retry_after") if isinstance(details, dict) else None
         return RateLimitExceededError(
             message,
             request_id=request_id,
@@ -178,6 +192,20 @@ def parse_error_response(
                 details=details,
             )
     elif status_code == 400:
+        if error_code == "COLLECTION_LIMIT_EXCEEDED":
+            from .exceptions import QuotaExceededError
+
+            current = details.get("current") if isinstance(details, dict) else None
+            limit = details.get("limit") if isinstance(details, dict) else None
+            return QuotaExceededError(
+                message,
+                "collections",
+                current=current,
+                limit=limit,
+                request_id=request_id,
+                status_code=status_code,
+                details=details,
+            )
         return ValidationError(
             message, request_id=request_id, status_code=status_code, details=details
         )

tests/test_utils.py

@@ -23,6 +23,7 @@
     PointNotFoundError,
     RequestTimeoutError,
     AetherfyVectorsException,
+    QuotaExceededError,
 )
 
 
@@ -241,6 +242,47 @@ def test_parse_error_response_400(self):
         error = parse_error_response(response_data, 400)
         assert isinstance(error, ValidationError)
 
+    def test_parse_error_response_400_collection_limit_exceeded(self):
+        """Test that COLLECTION_LIMIT_EXCEEDED maps to QuotaExceededError, not ValidationError."""
+        response_data = {
+            "error": {
+                "code": "COLLECTION_LIMIT_EXCEEDED",
+                "message": "Collection limit reached. Your free plan allows 3 collections.",
+                "current": 3,
+                "limit": 3,
+            }
+        }
+        error = parse_error_response(response_data, 400)
+        assert isinstance(error, QuotaExceededError)
+        assert error.quota_type == "collections"
+        assert error.current == 3
+        assert error.limit == 3
+        assert "Collection limit reached" in str(error)
+
+    def test_parse_error_response_429_storage_limit_exceeded(self):
+        """Test that STORAGE_LIMIT_EXCEEDED maps to QuotaExceededError, not RateLimitExceededError."""
+        response_data = {
+            "error": {
+                "code": "STORAGE_LIMIT_EXCEEDED",
+                "message": "Storage limit exceeded. Your free plan allows 512 MB.",
+                "current": 536870912,
+                "limit": 536870912,
+            }
+        }
+        error = parse_error_response(response_data, 429)
+        assert isinstance(error, QuotaExceededError)
+        assert error.quota_type == "storage"
+        assert error.current == 536870912
+        assert error.limit == 536870912
+        assert "Storage limit exceeded" in str(error)
+
+    def test_parse_error_response_429_rate_limit(self):
+        """Test that plain 429 without STORAGE_LIMIT_EXCEEDED still maps to RateLimitExceededError."""
+        from aetherfy_vectors.exceptions import RateLimitExceededError
+        response_data = {"message": "Too many requests", "request_id": "req_123"}
+        error = parse_error_response(response_data, 429)
+        assert isinstance(error, RateLimitExceededError)
+
     def test_parse_error_response_408(self):
         """Test parsing 408 request timeout error."""
         response_data = {"message": "Request Timeout", "request_id": "req_123"}