feat: better communicate limits in Core API errors

api/app/exceptions.py

@@ -1,2 +1,19 @@
+from rest_framework.views import exception_handler
+
+
 class ImproperlyConfiguredError(RuntimeError):
     pass
+
+
+def custom_api_exception_handler(exc, context):
+    # Call REST framework's default exception handler first,
+    # to get the standard error response.
+    response = exception_handler(exc, context)
+
+    if response is not None and hasattr(exc, "get_codes"):
+        if isinstance(response.data, dict) and "detail" in response.data:
+            codes = exc.get_codes()
+            if isinstance(codes, str):
+                response.data["code"] = codes
+
+    return response

api/app/settings/common.py

@@ -353,6 +353,7 @@
         "api_keys.authentication.MasterAPIKeyAuthentication",
         "oauth2_metadata.authentication.OAuth2BearerTokenAuthentication",
     ),
+    "EXCEPTION_HANDLER": "app.exceptions.custom_api_exception_handler",
     "PAGE_SIZE": 10,
     "UNICODE_JSON": False,
     "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",

api/organisations/exceptions.py

@@ -1,6 +1,11 @@
+from rest_framework import status
 from rest_framework.exceptions import APIException
 
 
 class OrganisationHasNoPaidSubscription(APIException):
-    status_code = 400
-    default_detail = "Organisation has no subscription"
+    status_code = status.HTTP_402_PAYMENT_REQUIRED
+    default_code = "invalid-plan"
+    default_detail = (
+        "Organisation has no subscription. "
+        "Please upgrade your plan: https://www.flagsmith.com/pricing"
+    )

api/organisations/subscriptions/exceptions.py

@@ -1,9 +1,18 @@
+from rest_framework import status
 from rest_framework.exceptions import APIException
 
 
-class InvalidSubscriptionPlanError(APIException):
-    status_code = 403
-    default_detail = "Organisation does not have a valid plan for this resource."
+class BaseInvalidPlanError(APIException):
+    status_code = status.HTTP_402_PAYMENT_REQUIRED
+    default_code = "invalid-plan"
+    default_detail = (
+        "Organisation does not have a valid plan for this resource. "
+        "Please upgrade your plan: https://www.flagsmith.com/pricing"
+    )
+
+
+class InvalidSubscriptionPlanError(BaseInvalidPlanError):
+    pass
 
 
 class CannotCancelChargebeeSubscription(APIException):
@@ -15,7 +24,7 @@ class UpgradeSeatsError(APIException):
 
 
 class UpgradeSeatsPaymentFailure(APIException):
-    status_code = 400
+    status_code = status.HTTP_400_BAD_REQUEST
     default_detail = (
         "Joining the organisation has failed due to a payment issue. "
         "Please contact your organisation's admin."
@@ -27,13 +36,15 @@ class UpgradeAPIUsageError(APIException):
 
 
 class UpgradeAPIUsagePaymentFailure(APIException):
-    status_code = 400
+    status_code = status.HTTP_400_BAD_REQUEST
     default_detail = (
         "API usage upgrade has failed due to a payment issue. "
         "If this persists, contact the organisation admin."
     )
 
 
-class SubscriptionDoesNotSupportSeatUpgrade(APIException):
-    status_code = 400
-    default_detail = "Please upgrade your plan to add additional seats/users"
+class SubscriptionDoesNotSupportSeatUpgrade(BaseInvalidPlanError):
+    default_detail = (
+        "Please upgrade your plan to add additional seats/users: "
+        "https://www.flagsmith.com/pricing"
+    )

api/projects/exceptions.py

@@ -1,3 +1,4 @@
+from rest_framework import status
 from rest_framework.exceptions import APIException
 
 
@@ -19,3 +20,36 @@
 class ProjectTooLargeError(APIException):
     status_code = 400
     default_detail = "Project is too large; Please contact support"
+
+
+class SystemLimitError(APIException):
+    status_code = status.HTTP_400_BAD_REQUEST
+    default_code = "system-limit"
+    default_detail = (
+        "System limit exceeded. Please contact support to adjust your limits: "
+        "https://docs.flagsmith.com/support#getting-in-touch"
+    )
+
+
+class DynamoNotEnabledError(APIException):
+    status_code = status.HTTP_400_BAD_REQUEST
+    default_detail = "Dynamo DB is not enabled for this project"
+
+
+class ProjectMigrationError(APIException):
+    status_code = status.HTTP_400_BAD_REQUEST
+    default_detail = "Migration is either already done or is in progress"
+
+
+class TooManyIdentitiesError(SystemLimitError):
+    default_detail = (
+        "Too many identities. Please contact support to adjust your limits: "
+        "https://docs.flagsmith.com/support#getting-in-touch"
+    )
+
+
+class ProjectTooLargeError(SystemLimitError):
+    default_detail = (
+        "Project is too large. Please contact support to adjust your limits: "
+        "https://docs.flagsmith.com/support#getting-in-touch"
+    )

api/tests/unit/organisations/invites/test_unit_invites_views.py

@@ -72,7 +72,7 @@ def test_get_invite_links__multiple_roles_exist__returns_all_links(
         assert all(attr in invite_link for attr in expected_attributes)
 
 
-def test_get_invite_links__seats_exceeded__returns_400(
+def test_get_invite_links__seats_exceeded__returns_402(
     settings: SettingsWrapper,
     organisation: Organisation,
     admin_client: APIClient,
@@ -91,7 +91,12 @@ def test_get_invite_links__seats_exceeded__returns_400(
     response = admin_client.get(url)
 
     # Then
-    assert response.status_code == status.HTTP_400_BAD_REQUEST
+    assert response.status_code == status.HTTP_402_PAYMENT_REQUIRED
+    assert response.json()["code"] == "invalid-plan"
+    assert (
+        response.json()["detail"]
+        == "Please upgrade your plan to add additional seats/users: https://www.flagsmith.com/pricing"
+    )
 
 
 def test_delete_invite_link__valid_invite__returns_204(
@@ -120,7 +125,7 @@ def test_delete_invite_link__valid_invite__returns_204(
     assert response.status_code == status.HTTP_204_NO_CONTENT
 
 
-def test_delete_invite_link__seats_exceeded__returns_400(
+def test_delete_invite_link__seats_exceeded__returns_402(
     organisation: Organisation,
     admin_client: APIClient,
     settings: SettingsWrapper,
@@ -137,7 +142,12 @@ def test_delete_invite_link__seats_exceeded__returns_400(
     response = admin_client.delete(url)
 
     # Then
-    assert response.status_code == status.HTTP_400_BAD_REQUEST
+    assert response.status_code == status.HTTP_402_PAYMENT_REQUIRED
+    assert response.json()["code"] == "invalid-plan"
+    assert (
+        response.json()["detail"]
+        == "Please upgrade your plan to add additional seats/users: https://www.flagsmith.com/pricing"
+    )
 
 
 def test_update_invite_link__patch_request__returns_405(  # type: ignore[no-untyped-def]
@@ -258,6 +268,7 @@ def test_create_invite__permission_group_from_another_org__returns_400(
     )
 
     # Then
+    # Validation error, stays 400
     assert response.status_code == status.HTTP_400_BAD_REQUEST
 
     response_json = response.json()
@@ -268,7 +279,7 @@ def test_create_invite__permission_group_from_another_org__returns_400(
     }
 
 
-def test_create_invite__seats_exceeded__returns_400(
+def test_create_invite__seats_exceeded__returns_402(
     admin_client: APIClient,
     organisation: Organisation,
     user_permission_group: UserPermissionGroup,
@@ -286,10 +297,11 @@ def test_create_invite__seats_exceeded__returns_400(
         url, data=json.dumps(data), content_type="application/json"
     )
     # Then
-    assert response.status_code == status.HTTP_400_BAD_REQUEST
+    assert response.status_code == status.HTTP_402_PAYMENT_REQUIRED
+    assert response.json()["code"] == "invalid-plan"
     assert (
         response.json()["detail"]
-        == "Please upgrade your plan to add additional seats/users"
+        == "Please upgrade your plan to add additional seats/users: https://www.flagsmith.com/pricing"
     )
 
 
@@ -346,7 +358,7 @@ def test_update_invite__put_request__returns_405(  # type: ignore[no-untyped-def
         (lazy_fixture("invite_link"), "api-v1:users:user-join-organisation-link"),
     ],
 )
-def test_join_organisation__exceeds_plan_limit_saas__returns_400(
+def test_join_organisation__exceeds_plan_limit_saas__returns_402(
     staff_client: APIClient,
     invite_object: Invite | InviteLink,
     url: str,
@@ -359,10 +371,11 @@ def test_join_organisation__exceeds_plan_limit_saas__returns_400(
     response = staff_client.post(url)
 
     # Then
-    assert response.status_code == status.HTTP_400_BAD_REQUEST
+    assert response.status_code == status.HTTP_402_PAYMENT_REQUIRED
+    assert response.json()["code"] == "invalid-plan"
     assert (
         response.json()["detail"]
-        == "Please upgrade your plan to add additional seats/users"
+        == "Please upgrade your plan to add additional seats/users: https://www.flagsmith.com/pricing"
     )
 
 
@@ -374,7 +387,7 @@ def test_join_organisation__exceeds_plan_limit_saas__returns_400(
         (lazy_fixture("invite_link"), "api-v1:users:user-join-organisation-link"),
     ],
 )
-def test_join_organisation__exceeds_plan_limit_self_hosted__returns_400(
+def test_join_organisation__exceeds_plan_limit_self_hosted__returns_402(
     staff_client: APIClient,
     invite_object: Invite | InviteLink,
     url: str,
@@ -391,10 +404,11 @@ def test_join_organisation__exceeds_plan_limit_self_hosted__returns_400(
     response = staff_client.post(url)
 
     # Then
-    assert response.status_code == status.HTTP_400_BAD_REQUEST
+    assert response.status_code == status.HTTP_402_PAYMENT_REQUIRED
+    assert response.json()["code"] == "invalid-plan"
     assert (
         response.json()["detail"]
-        == "Please upgrade your plan to add additional seats/users"
+        == "Please upgrade your plan to add additional seats/users: https://www.flagsmith.com/pricing"
     )
 
 

api/tests/unit/projects/test_unit_projects_views.py

@@ -590,7 +590,11 @@ def test_migrate_to_edge__too_many_identities__returns_400(  # type: ignore[no-u
 
     # Then
     assert response.status_code == status.HTTP_400_BAD_REQUEST
-    assert response.json()["detail"] == "Too many identities; Please contact support"
+    assert response.json()["code"] == "system-limit"
+    assert (
+        response.json()["detail"]
+        == "Too many identities. Please contact support to adjust your limits: https://docs.flagsmith.com/support#getting-in-touch"
+    )
     mocked_identity_migrator.assert_not_called()
 
 
@@ -611,7 +615,11 @@ def test_migrate_to_edge__too_many_features__returns_400(  # type: ignore[no-unt
 
     # Then
     assert response.status_code == status.HTTP_400_BAD_REQUEST
-    assert response.json()["detail"] == "Project is too large; Please contact support"
+    assert response.json()["code"] == "system-limit"
+    assert (
+        response.json()["detail"]
+        == "Project is too large. Please contact support to adjust your limits: https://docs.flagsmith.com/support#getting-in-touch"
+    )
     mocked_identity_migrator.assert_not_called()
 
 
@@ -639,7 +647,11 @@ def test_migrate_to_edge__too_many_segments__returns_400(  # type: ignore[no-unt
 
     # Then
     assert response.status_code == status.HTTP_400_BAD_REQUEST
-    assert response.json()["detail"] == "Project is too large; Please contact support"
+    assert response.json()["code"] == "system-limit"
+    assert (
+        response.json()["detail"]
+        == "Project is too large. Please contact support to adjust your limits: https://docs.flagsmith.com/support#getting-in-touch"
+    )
     mocked_identity_migrator.assert_not_called()
 
 
@@ -672,7 +684,11 @@ def test_migrate_to_edge__too_many_segment_overrides__returns_400(  # type: igno
 
     # Then
     assert response.status_code == status.HTTP_400_BAD_REQUEST
-    assert response.json()["detail"] == "Project is too large; Please contact support"
+    assert response.json()["code"] == "system-limit"
+    assert (
+        response.json()["detail"]
+        == "Project is too large. Please contact support to adjust your limits: https://docs.flagsmith.com/support#getting-in-touch"
+    )
     mocked_identity_migrator.assert_not_called()