@@ -16,7 +16,7 @@ src/smallestai/version.py
 # DevX: actionable error messages + PlanNotEntitledError specialization.
 src/smallestai/core/api_error.py
 src/smallestai/core/_error_hints.py
-src/smallestai/atoms/errors/forbidden_error.py
+src/smallestai/atoms/errors/bad_request_error.py
 src/smallestai/errors.py
 
 # Customer-added files (generator never produces these)
 
@@ -9,7 +9,7 @@
     from . import atoms, errors, waves
     from ._default_clients import DefaultAioHttpClient, DefaultAsyncHttpxClient
     from .atoms.client import AsyncAtomsClient, AtomsClient
-    from .atoms.errors.forbidden_error import PlanNotEntitledError
+    from .atoms.errors.bad_request_error import PlanNotEntitledError
     from .client import AsyncSmallestAI, SmallestAI
     from .environment import SmallestAIEnvironment
     from .version import __version__
@@ -21,7 +21,7 @@
     "AtomsClient": ".atoms.client",
     "DefaultAioHttpClient": "._default_clients",
     "DefaultAsyncHttpxClient": "._default_clients",
-    "PlanNotEntitledError": ".atoms.errors.forbidden_error",
+    "PlanNotEntitledError": ".atoms.errors.bad_request_error",
     "SmallestAI": ".client",
     "SmallestAIEnvironment": ".environment",
     "WavesClient": ".waves.client",
 
@@ -1,10 +1,31 @@
-# This file was auto-generated by Fern from our API Definition.
+# Hand-maintained (see .fernignore). Kept out of regeneration to auto-specialize
+# a plan/entitlement-gated 400 into PlanNotEntitledError. Re-apply after a regen.
 
 import typing
 
+from ...core._error_hints import looks_plan_gated
 from ...core.api_error import ApiError
 
 
 class BadRequestError(ApiError):
+    def __new__(cls, body: typing.Any = None, headers: typing.Optional[typing.Dict[str, str]] = None):
+        # The platform returns plan/entitlement gating as a 400 with an
+        # "…upgrade to a higher plan…" message (see access.middleware.ts). Return
+        # it as PlanNotEntitledError so callers can catch it distinctly. It
+        # subclasses BadRequestError, so `except BadRequestError` still works.
+        if cls is BadRequestError and looks_plan_gated(body):
+            return super().__new__(PlanNotEntitledError)
+        return super().__new__(cls)
+
     def __init__(self, body: typing.Any, headers: typing.Optional[typing.Dict[str, str]] = None):
         super().__init__(status_code=400, headers=headers, body=body)
+
+
+class PlanNotEntitledError(BadRequestError):
+    """A request rejected because the org's plan doesn't include the feature (or a
+    plan limit was hit) — the platform returns HTTP 400 with a "…please upgrade to
+    a higher plan…" message. Subclass of BadRequestError, so `except
+    BadRequestError` still catches it. Gated features include campaigns, knowledge
+    base, webhooks, integrations, phone numbers, inbound/outbound telephony, and
+    the waves models. Detection matches the platform message
+    (access.middleware.ts) — see SDK_ESCALATIONS.log."""
@@ -1,29 +1,10 @@
-# Hand-maintained (see .fernignore). Kept out of regeneration to auto-specialize
-# a plan-gated 403 into PlanNotEntitledError. Re-apply after a regen.
+# This file was auto-generated by Fern from our API Definition.
 
 import typing
 
-from ...core._error_hints import looks_plan_gated
 from ...core.api_error import ApiError
 
 
 class ForbiddenError(ApiError):
-    def __new__(cls, body: typing.Any = None, headers: typing.Optional[typing.Dict[str, str]] = None):
-        # A 403 whose body looks like a plan/entitlement gate is returned as a
-        # PlanNotEntitledError so callers can `except PlanNotEntitledError`.
-        # It subclasses ForbiddenError, so existing `except ForbiddenError`
-        # handlers keep working — fully backward-compatible.
-        if cls is ForbiddenError and looks_plan_gated(body):
-            return super().__new__(PlanNotEntitledError)
-        return super().__new__(cls)
-
     def __init__(self, body: typing.Any, headers: typing.Optional[typing.Dict[str, str]] = None):
         super().__init__(status_code=403, headers=headers, body=body)
-
-
-class PlanNotEntitledError(ForbiddenError):
-    """A 403 that looks like a plan / entitlement gate — the API key is valid but
-    the feature needs a higher plan (e.g. an Enterprise-only feature such as DNC
-    writes). Subclass of ForbiddenError, so `except ForbiddenError` still catches
-    it. The exact detection is a heuristic until the platform returns a stable
-    machine-readable code (see SDK_ESCALATIONS.log)."""
@@ -1,60 +1,76 @@
-"""Actionable-error helpers shared by the enriched ApiError / ForbiddenError.
+"""Actionable-error helpers shared by the enriched ApiError / BadRequestError.
 
 Hand-maintained (see .fernignore). Kept dependency-free (no imports of the error
 classes) so the error modules can import it without a cycle.
+
+The plan-gate detection matches the platform's payment-entitlement middleware
+(atoms main-backend access.middleware.ts): a gated feature is rejected with an
+HTTP 400 body `{ "status": false, "errors": ["… please upgrade to a higher plan …"] }`.
 """
 
 import typing
 
-# Markers that suggest a 403 is a plan/entitlement gate (feature needs a higher
-# plan) rather than a generic permission denial. Best-effort heuristic until the
-# platform exposes a stable machine-readable code — see SDK_ESCALATIONS.log.
-# Kept reasonably specific to avoid mislabelling ordinary permission errors.
+# Substrings that identify a plan/entitlement-gated 400 (feature not on plan, or
+# a plan limit hit). Both platform message families contain "upgrade to a higher
+# plan"; the two lead-ins add resilience to small wording changes.
 _PLAN_GATE_MARKERS = (
-    "your plan",
-    "upgrade",
-    "entitl",  # entitled / entitlement
-    "not available on your",
-    "not enabled for your",
-    "enterprise plan",
-    "subscription required",
-    "plan_upgrade_required",
-    "feature_not_entitled",
-    "requires a paid",
+    "upgrade to a higher plan",
+    "no access to",
+    "reached the maximum",
 )
 
+# Identifies an org allow-list gate (HTTP 403) — not plan-upgradeable by the user
+# (e.g. GPT 5.2, conversational-flow agents).
+_ORG_GATE_MARKER = "not available for your organization"
+
 
 def _body_text(body: typing.Any) -> str:
     if body is None:
         return ""
     if isinstance(body, str):
         return body
     if isinstance(body, dict):
-        parts = [str(body.get(k, "")) for k in ("message", "error", "code", "detail", "reason")]
+        # Platform error envelope is {status: false, errors: [...]}; also handle
+        # the common single-field shapes.
+        errors = body.get("errors")
+        parts: typing.List[str] = []
+        if isinstance(errors, (list, tuple)):
+            parts.extend(str(e) for e in errors)
+        elif errors:
+            parts.append(str(errors))
+        parts.extend(str(body.get(k, "")) for k in ("message", "error", "detail", "reason"))
         joined = " ".join(p for p in parts if p)
         return joined or str(body)
     return str(body)
 
 
 def looks_plan_gated(body: typing.Any) -> bool:
-    """Best-effort: does this 403 body look like a plan/entitlement gate?"""
+    """Best-effort: does this 400 body look like a plan/entitlement gate?"""
     text = _body_text(body).lower()
     return bool(text) and any(m in text for m in _PLAN_GATE_MARKERS)
 
 
+def _looks_org_gated(body: typing.Any) -> bool:
+    return _ORG_GATE_MARKER in _body_text(body).lower()
+
+
 def hint_for(status_code: typing.Optional[int], body: typing.Any) -> str:
     """A one-line, actionable hint to append to an error message, or '' if none."""
     if status_code == 401:
         return (
             "Authentication failed. Check your API key (SMALLEST_API_KEY) — "
             "get one at https://app.smallest.ai/dashboard/api-keys."
         )
+    if status_code == 400 and looks_plan_gated(body):
+        return (
+            "This feature (or limit) is not included in your current plan. "
+            "Upgrade at https://app.smallest.ai or contact your account team."
+        )
     if status_code == 403:
-        if looks_plan_gated(body):
+        if _looks_org_gated(body):
             return (
-                "This looks like a plan-gated feature. It may require a plan "
-                "upgrade (e.g. an Enterprise feature) — check your plan at "
-                "https://app.smallest.ai or contact your account team."
+                "This feature is limited to specific organizations. "
+                "Contact your account team to enable it."
             )
         return "Your API key is valid but is not permitted to perform this action."
     return ""
@@ -8,9 +8,9 @@
 distinctly while ``except ForbiddenError`` still catches it.
 """
 
-from smallestai.atoms.errors.bad_request_error import BadRequestError
+from smallestai.atoms.errors.bad_request_error import BadRequestError, PlanNotEntitledError
 from smallestai.atoms.errors.conflict_error import ConflictError
-from smallestai.atoms.errors.forbidden_error import ForbiddenError, PlanNotEntitledError
+from smallestai.atoms.errors.forbidden_error import ForbiddenError
 from smallestai.atoms.errors.not_found_error import NotFoundError
 from smallestai.atoms.errors.too_many_requests_error import TooManyRequestsError
 from smallestai.atoms.errors.unauthorized_error import UnauthorizedError
 
@@ -1,49 +1,64 @@
 """DevX: actionable error messages + PlanNotEntitledError specialization.
 
-A plan-gated 403 should be catchable as PlanNotEntitledError while staying a
-ForbiddenError (backward-compatible). Error messages should carry an actionable
-hint for auth (401) and plan-gated (403) failures.
+The platform returns plan/entitlement gating as an HTTP 400 with body
+`{status: false, errors: ["… please upgrade to a higher plan …"]}` (see atoms
+main-backend access.middleware.ts). It should surface as PlanNotEntitledError
+while staying a BadRequestError (backward-compatible).
 """
 import unittest
 
 from smallestai import PlanNotEntitledError as PlanNotEntitledFromRoot
-from smallestai.atoms.errors.forbidden_error import ForbiddenError, PlanNotEntitledError
+from smallestai.atoms.errors.bad_request_error import BadRequestError, PlanNotEntitledError
 from smallestai.atoms.errors.unauthorized_error import UnauthorizedError
 from smallestai.core.api_error import ApiError
 from smallestai.errors import PlanNotEntitledError as PlanNotEntitledFromErrors
 
+_PLAN_GATED_BODY = {
+    "status": False,
+    "errors": ["Your plan has no access to campaigns, please upgrade to a higher plan to access this feature"],
+}
+_LIMIT_BODY = {
+    "status": False,
+    "errors": ["You have reached the maximum number of agents for your plan, please upgrade to a higher plan to create more agents"],
+}
+
 
 class ErrorDevxTest(unittest.TestCase):
-    def test_plan_gated_403_becomes_plan_not_entitled(self):
-        err = ForbiddenError(body={"message": "DNC is not available on your plan. Upgrade to Enterprise."})
+    def test_plan_gated_400_becomes_plan_not_entitled(self):
+        err = BadRequestError(body=_PLAN_GATED_BODY)
         self.assertIsInstance(err, PlanNotEntitledError)
-        self.assertIsInstance(err, ForbiddenError)  # backward-compatible
-        self.assertEqual(err.status_code, 403)
+        self.assertIsInstance(err, BadRequestError)
+        self.assertEqual(err.status_code, 400)
+
+    def test_plan_limit_400_also_specializes(self):
+        self.assertIsInstance(BadRequestError(body=_LIMIT_BODY), PlanNotEntitledError)
 
-    def test_generic_403_stays_forbidden(self):
-        err = ForbiddenError(body={"message": "You do not have access to this resource."})
-        self.assertIsInstance(err, ForbiddenError)
+    def test_generic_400_stays_bad_request(self):
+        err = BadRequestError(body={"status": False, "errors": ["voiceId is required"]})
+        self.assertIsInstance(err, BadRequestError)
         self.assertNotIsInstance(err, PlanNotEntitledError)
 
-    def test_explicit_plan_error_construction(self):
-        err = PlanNotEntitledError(body={"message": "feature_not_entitled"})
-        self.assertIsInstance(err, PlanNotEntitledError)
-        self.assertEqual(err.status_code, 403)
+    def test_catch_as_plan_not_entitled(self):
+        try:
+            raise BadRequestError(body=_PLAN_GATED_BODY)
+        except PlanNotEntitledError:
+            pass
+        else:
+            self.fail("expected PlanNotEntitledError")
 
     def test_exported_symbols_are_the_same_class(self):
         self.assertIs(PlanNotEntitledFromRoot, PlanNotEntitledError)
         self.assertIs(PlanNotEntitledFromErrors, PlanNotEntitledError)
 
     def test_401_message_has_auth_hint(self):
-        msg = str(UnauthorizedError(body={"message": "invalid token"}))
-        self.assertIn("SMALLEST_API_KEY", msg)
+        self.assertIn("SMALLEST_API_KEY", str(UnauthorizedError(body={"errors": ["invalid token"]})))
 
     def test_plan_gated_message_has_upgrade_hint(self):
-        msg = str(ForbiddenError(body={"message": "requires a paid plan; upgrade your plan"}))
-        self.assertIn("plan-gated", msg.lower())
+        msg = str(BadRequestError(body=_PLAN_GATED_BODY)).lower()
+        self.assertIn("plan", msg)
+        self.assertIn("upgrade", msg)
 
-    def test_success_case_no_hint_noise(self):
-        # A non-auth, non-403 error keeps a clean message.
+    def test_no_hint_noise_on_plain_error(self):
         msg = str(ApiError(status_code=500, body="boom"))
         self.assertIn("boom", msg)
         self.assertNotIn("SMALLEST_API_KEY", msg)