form4api 0.6.0__tar.gz → 0.7.0__tar.gz

{form4api-0.6.0 → form4api-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading data
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -183,27 +183,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.6.0 → form4api-0.7.0}/README.md

@@ -164,27 +164,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.6.0 → form4api-0.7.0}/form4api/__init__.py

@@ -1,30 +1,38 @@
-from form4api._client import AsyncForm4ApiClient, Form4ApiClient
-from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
-from form4api._types import (
-    Company,
-    Insider,
-    InsiderSignal,
-    Transaction,
-    WebhookCreated,
-    WebhookEvent,
-    WebhookSubscription,
-)
-from form4api._webhook_utils import verify_webhook
-
-__all__ = [
-    "Form4ApiClient",
-    "AsyncForm4ApiClient",
-    "Form4ApiError",
-    "AuthError",
-    "PlanError",
-    "NotFoundError",
-    "RateLimitError",
-    "Transaction",
-    "Insider",
-    "Company",
-    "InsiderSignal",
-    "WebhookCreated",
-    "WebhookEvent",
-    "WebhookSubscription",
-    "verify_webhook",
-]
+from form4api._client import AsyncForm4ApiClient, Form4ApiClient
+from form4api._errors import (
+    AuthError,
+    Form4ApiError,
+    NotFoundError,
+    PaginationLimitError,
+    PlanError,
+    RateLimitError,
+)
+from form4api._types import (
+    Company,
+    Insider,
+    InsiderSignal,
+    Transaction,
+    WebhookCreated,
+    WebhookEvent,
+    WebhookSubscription,
+)
+from form4api._webhook_utils import verify_webhook
+
+__all__ = [
+    "Form4ApiClient",
+    "AsyncForm4ApiClient",
+    "Form4ApiError",
+    "AuthError",
+    "PlanError",
+    "PaginationLimitError",
+    "NotFoundError",
+    "RateLimitError",
+    "Transaction",
+    "Insider",
+    "Company",
+    "InsiderSignal",
+    "WebhookCreated",
+    "WebhookEvent",
+    "WebhookSubscription",
+    "verify_webhook",
+]

form4api-0.7.0/form4api/_errors.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import re
+
+
+class Form4ApiError(Exception):
+    def __init__(self, message: str, status_code: int, error_code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+
+
+class AuthError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 401, error_code)
+
+
+class PlanError(Form4ApiError):
+    """Raised on 402 PLAN_REQUIRED.
+
+    ``required_plan`` is the minimum plan that unlocks the endpoint (e.g.
+    ``"Business"``), ``current_plan`` is the plan the calling key is on, and
+    ``upgrade_url`` is where to upgrade. All three may be ``None`` against
+    backends older than 2026-08-05, which carried the plan names only as prose
+    inside ``message``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        required_plan: str | None = None,
+        current_plan: str | None = None,
+        upgrade_url: str | None = None,
+    ) -> None:
+        super().__init__(message, 402, "PLAN_REQUIRED")
+        self.required_plan = required_plan
+        self.current_plan = current_plan
+        self.upgrade_url = upgrade_url
+
+
+class NotFoundError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 404, error_code)
+
+
+class RateLimitError(Form4ApiError):
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message, 429, "RATE_LIMIT_EXCEEDED")
+        self.retry_after = retry_after
+
+
+# Backend message shape for the plan-gated *pagination depth* 402 (see
+# PaginationHelpers.MaxPageFor / TransactionsEndpoints.cs / CongressEndpoints.cs
+# on the API). This is deliberately narrow: `error_code` is "PLAN_REQUIRED" for
+# EVERY 402 the API returns — a whole-endpoint plan gate (e.g. GET /v1/signals
+# on a sub-Business key) and a plan-gated query parameter both use the same
+# code — so the message text is the only reliable signal that a given 402 is
+# specifically the depth limit rather than some other plan gate. If the
+# backend ever changes this message shape, the regex stops matching and
+# `paginate()` re-raises the original `PlanError` untouched instead of
+# mislabeling an unrelated 402.
+_PAGINATION_DEPTH_MESSAGE_RE = re.compile(r"pagination depth on /v1/", re.IGNORECASE)
+
+
+def is_pagination_depth_error(err: Exception) -> bool:
+    """True when `err` is specifically the plan-gated pagination-depth 402 that
+    `paginate()` knows how to turn into a `PaginationLimitError`."""
+    return isinstance(err, PlanError) and bool(_PAGINATION_DEPTH_MESSAGE_RE.search(str(err)))
+
+
+class PaginationLimitError(PlanError):
+    """Raised by `paginate()` (on `transactions` and `signals`) when the backend
+    rejects the next page because the calling key's plan has reached its
+    pagination depth limit (Free: 20 pages, Starter: 100, Pro+: unlimited).
+
+    Pages already yielded before this point were real, complete pages — this
+    error only means iteration stopped early, not that any data already
+    delivered to the caller was wrong. `pages_yielded` tells you exactly how
+    many. The original `PlanError` is chained as `__cause__` (via `raise ... from err`).
+
+    **Subclasses PlanError deliberately.** Before this type existed, `paginate()`
+    raised a plain `PlanError` at the depth limit, so `except PlanError:` was the
+    documented way to handle it. Subclassing keeps every one of those handlers
+    working while letting new code catch the narrower type — and it is the
+    truthful relationship anyway, since this IS a 402 PLAN_REQUIRED. Making it a
+    sibling would break existing callers for no gain.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        pages_yielded: int,
+        cause: PlanError | None = None,
+    ) -> None:
+        # Carry the upgrade metadata through from the original 402 where the
+        # backend supplied it, so a caller can link straight to the upgrade page
+        # without unwrapping __cause__ themselves. The depth-limit branch
+        # populates upgrade_url but leaves required_plan/current_plan None.
+        super().__init__(
+            message,
+            cause.required_plan if cause else None,
+            cause.current_plan if cause else None,
+            cause.upgrade_url if cause else None,
+        )
+        self.pages_yielded = pages_yielded

{form4api-0.6.0 → form4api-0.7.0}/form4api/resources/_signals.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 
 from collections.abc import AsyncGenerator
 
+from form4api._errors import PaginationLimitError, PlanError, is_pagination_depth_error
 from form4api._generated import GeneratedAsyncSignalsResource, GeneratedSignalsResource
 from form4api._types import InsiderSignal
 
@@ -58,16 +59,39 @@ class SignalsResource(GeneratedSignalsResource):
         cluster_buy: bool | None = None,
         cluster_sell: bool | None = None,
         per_page: int = 100,
+        max_pages: int | None = None,
     ) -> Generator[list[InsiderSignal], None, None]:
+        """Pages through /v1/signals until the data runs out (a short or empty
+        page) or the calling key's plan-gated pagination depth is exceeded —
+        see `TransactionsResource.paginate` for the full rationale. That 402
+        is NOT swallowed; it becomes a `PaginationLimitError` after every page
+        already yielded has been delivered to the caller. Pass `max_pages` to
+        stop deliberately before that happens.
+        """
         page = 1
+        pages_yielded = 0
         while True:
-            batch = self.list(
-                ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = self.list(
+                    ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"signals.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1
@@ -102,16 +126,34 @@ class AsyncSignalsResource(GeneratedAsyncSignalsResource):
         cluster_buy: bool | None = None,
         cluster_sell: bool | None = None,
         per_page: int = 100,
+        max_pages: int | None = None,
     ) -> AsyncGenerator[list[InsiderSignal], None]:
+        """Async twin of `SignalsResource.paginate` — same depth-limit
+        semantics, see there for the full rationale."""
         page = 1
+        pages_yielded = 0
         while True:
-            batch = await self.list(
-                ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = await self.list(
+                    ticker=ticker, cluster_buy=cluster_buy, cluster_sell=cluster_sell,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"signals.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1

{form4api-0.6.0 → form4api-0.7.0}/form4api/resources/_transactions.py

@@ -3,6 +3,7 @@
 from collections.abc import AsyncGenerator, Generator
 from typing import TYPE_CHECKING
 
+from form4api._errors import PaginationLimitError, PlanError, is_pagination_depth_error
 from form4api._types import Transaction
 
 if TYPE_CHECKING:
@@ -121,23 +122,49 @@ class TransactionsResource:
         min_shares: float | None = None,
         max_shares: float | None = None,
         per_page: int = 50,
+        max_pages: int | None = None,
     ) -> Generator[list[Transaction], None, None]:
+        """Pages through /v1/transactions until the data runs out (a short or
+        empty page) or, since the backend's 2026-08-01 plan-gated pagination
+        depth (Free: 20 pages, Starter: 100, Pro+: unlimited), the next page is
+        rejected with a 402. That 402 is NOT swallowed — a scripted caller who
+        silently stopped there would see what looks like "no more data" and
+        never learn their dataset was truncated. Instead this raises
+        `PaginationLimitError` mid-iteration, after every page already yielded
+        has been delivered to the caller. Pass `max_pages` to stop deliberately
+        before that ever happens.
+        """
         page = 1
+        pages_yielded = 0
         while True:
-            batch = self.list(
-                ticker=ticker, cik=cik, insider_cik=insider_cik,
-                code=code, from_date=from_date, to_date=to_date,
-                exclude_10b5=exclude_10b5,
-                codes=codes, exclude_codes=exclude_codes,
-                category=category, exclude_category=exclude_category,
-                exclude_derivative=exclude_derivative, significant=significant,
-                min_value=min_value, max_value=max_value,
-                min_shares=min_shares, max_shares=max_shares,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = self.list(
+                    ticker=ticker, cik=cik, insider_cik=insider_cik,
+                    code=code, from_date=from_date, to_date=to_date,
+                    exclude_10b5=exclude_10b5,
+                    codes=codes, exclude_codes=exclude_codes,
+                    category=category, exclude_category=exclude_category,
+                    exclude_derivative=exclude_derivative, significant=significant,
+                    min_value=min_value, max_value=max_value,
+                    min_shares=min_shares, max_shares=max_shares,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"transactions.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1
@@ -205,21 +232,39 @@ class AsyncTransactionsResource:
         min_shares: float | None = None,
         max_shares: float | None = None,
         per_page: int = 50,
+        max_pages: int | None = None,
     ) -> AsyncGenerator[list[Transaction], None]:
+        """Async twin of `TransactionsResource.paginate` — same depth-limit
+        semantics, see there for the full rationale."""
         page = 1
+        pages_yielded = 0
         while True:
-            batch = await self.list(
-            ticker=ticker, cik=cik, insider_cik=insider_cik, code=code,
-            from_date=from_date, to_date=to_date, exclude_10b5=exclude_10b5,
-            codes=codes, exclude_codes=exclude_codes, category=category,
-            exclude_category=exclude_category, exclude_derivative=exclude_derivative,
-            significant=significant, min_value=min_value, max_value=max_value,
-            min_shares=min_shares, max_shares=max_shares,
-                page=page, per_page=per_page,
-            )
+            if max_pages is not None and pages_yielded >= max_pages:
+                break
+
+            try:
+                batch = await self.list(
+                    ticker=ticker, cik=cik, insider_cik=insider_cik, code=code,
+                    from_date=from_date, to_date=to_date, exclude_10b5=exclude_10b5,
+                    codes=codes, exclude_codes=exclude_codes, category=category,
+                    exclude_category=exclude_category, exclude_derivative=exclude_derivative,
+                    significant=significant, min_value=min_value, max_value=max_value,
+                    min_shares=min_shares, max_shares=max_shares,
+                    page=page, per_page=per_page,
+                )
+            except PlanError as err:
+                if is_pagination_depth_error(err):
+                    raise PaginationLimitError(
+                        f"transactions.paginate() stopped after yielding {pages_yielded} page(s) — {err}",
+                        pages_yielded,
+                        err,
+                    ) from err
+                raise
+
             if not batch:
                 break
             yield batch
+            pages_yielded += 1
             if len(batch) < per_page:
                 break
             page += 1

{form4api-0.6.0 → form4api-0.7.0}/form4api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading data
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -183,27 +183,52 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 
 ### Pagination
 
+`paginate()` pages through the data until it runs out (a short or empty page)
+or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20
+pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402.
+That 402 is not swallowed — it raises `PaginationLimitError` mid-iteration,
+after every page already yielded has been delivered to your loop. Pages you
+already received are real and complete; the error only means iteration
+stopped early. Pass `max_pages` to stop deliberately before that ever
+happens, or catch `PaginationLimitError` to know when a Free/Starter key ran
+out of depth on a bulk pull:
+
 ```python
+from form4api import PaginationLimitError
+
 # transactions.paginate() — yields one list per page automatically
 all_txns = []
-for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
-    all_txns.extend(batch)
+try:
+    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
+        all_txns.extend(batch)
+except PaginationLimitError as e:
+    print(f"Stopped after {e.pages_yielded} pages — {e}")
+    # all_txns still holds every page yielded before the limit hit
 
 # signals.paginate()
 all_signals = []
-for batch in client.signals.paginate(cluster_buy=True, per_page=100):
+for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
     all_signals.extend(batch)
 ```
 
 ## Error handling
 
 ```python
-from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    PlanError,
+    PaginationLimitError,
+    RateLimitError,
+    NotFoundError,
+)
 
 client = Form4ApiClient("YOUR_API_KEY")
 
 try:
     signals = client.signals.list()
+except PaginationLimitError as e:
+    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
 except PlanError as e:
     print(f"Upgrade required")
 except RateLimitError as e:

{form4api-0.6.0 → form4api-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "form4api"
-version = "0.6.0"
+version = "0.7.0"
 description = "Python client for the Form4API — real-time SEC Form 4 insider trading data"
 keywords = ["insider-trading", "sec", "sec-edgar", "edgar", "form-4", "form4", "form-144", "13f", "13f-hr", "financial-data", "stock-market", "stocks", "fintech", "api", "sdk", "webhooks", "form4api"]
 requires-python = ">=3.11"

{form4api-0.6.0 → form4api-0.7.0}/tests/test_client.py

@@ -6,6 +6,7 @@ from form4api import (
     Form4ApiClient,
     AuthError,
     NotFoundError,
+    PaginationLimitError,
     PlanError,
     RateLimitError,
     Form4ApiError,
@@ -161,6 +162,128 @@ def test_transactions_paginate_stops_on_short_page(client):
     assert pages[0][0].ticker == "AAPL"
 
 
+@respx.mock
+def test_transactions_paginate_raises_pagination_limit_error_after_delivering_prior_pages(client):
+    """The plan-gated pagination-depth 402 is not swallowed: it becomes a
+    PaginationLimitError raised mid-iteration, after every page already
+    yielded has been delivered to the caller."""
+    call = {"n": 0}
+
+    def handler(_request):
+        call["n"] += 1
+        if call["n"] <= 2:
+            return httpx.Response(200, json=[TX, TX])
+        return httpx.Response(
+            402,
+            json={
+                "error": {
+                    "code": "PLAN_REQUIRED",
+                    "message": (
+                        "Page 3 is beyond the Free plan's pagination depth on /v1/transactions "
+                        "(2 pages). The Starter plan reaches 100 pages and Pro removes the limit "
+                        "— upgrade at https://form4api.com/dashboard/billing?from=page_depth_402. "
+                        "For a bulk historical pull, GET /v1/transactions/export (Business plan) "
+                        "streams the full filtered set as CSV instead of paging."
+                    ),
+                    "requestId": "req_test",
+                }
+            },
+        )
+
+    respx.get(f"{BASE}/v1/transactions").mock(side_effect=handler)
+
+    pages = []
+    caught = None
+    try:
+        for page in client.transactions.paginate(per_page=2):
+            pages.append(page)
+    except PaginationLimitError as err:
+        caught = err
+
+    assert len(pages) == 2
+    assert caught is not None
+    assert caught.pages_yielded == 2
+    assert "yielding 2 page(s)" in str(caught)
+    assert "/v1/transactions/export" in str(caught)
+    assert isinstance(caught.__cause__, PlanError)
+
+    # Backward compatibility, and the reason PaginationLimitError subclasses
+    # PlanError rather than sitting beside it. Before this type existed,
+    # paginate() raised a plain PlanError here, so `except PlanError:` was the
+    # documented way to handle the depth limit. If this assertion ever fails,
+    # every caller written against the old behaviour is silently no longer
+    # catching this — an uncaught exception rather than a handled upgrade path.
+    assert isinstance(caught, PlanError)
+    # The upgrade metadata is carried through from the original 402 so callers
+    # do not have to unwrap __cause__ to find it.
+    assert caught.upgrade_url == caught.__cause__.upgrade_url
+
+
+@respx.mock
+def test_transactions_paginate_max_pages_stops_before_depth_limit(client):
+    respx.get(f"{BASE}/v1/transactions").mock(return_value=httpx.Response(200, json=[TX, TX]))
+    pages = list(client.transactions.paginate(per_page=2, max_pages=3))
+    assert len(pages) == 3
+
+
+@respx.mock
+def test_transactions_paginate_does_not_swallow_or_mislabel_non_402_error(client):
+    call = {"n": 0}
+
+    def handler(_request):
+        call["n"] += 1
+        if call["n"] == 1:
+            return httpx.Response(200, json=[TX, TX])
+        return httpx.Response(500, json={})
+
+    respx.get(f"{BASE}/v1/transactions").mock(side_effect=handler)
+
+    pages = []
+    caught = None
+    try:
+        for page in client.transactions.paginate(per_page=2):
+            pages.append(page)
+    except Form4ApiError as err:
+        caught = err
+
+    assert len(pages) == 1
+    assert caught is not None
+    assert not isinstance(caught, PaginationLimitError)
+    assert caught.status_code == 500
+
+
+@respx.mock
+def test_signals_paginate_reraises_non_depth_402_as_plan_error(client):
+    """GET /v1/signals is gated at the whole-endpoint level (Business plan) —
+    this 402 has nothing to do with pagination depth, and must not be
+    rewritten as though it were the depth limit."""
+    respx.get(f"{BASE}/v1/signals").mock(
+        return_value=httpx.Response(
+            402,
+            json={
+                "error": {
+                    "code": "PLAN_REQUIRED",
+                    "message": "This endpoint requires the Business plan or higher. Your current plan is Free.",
+                    "requestId": "req_test",
+                    "requiredPlan": "Business",
+                    "currentPlan": "Free",
+                }
+            },
+        )
+    )
+
+    caught = None
+    try:
+        for _page in client.signals.paginate():
+            pass
+    except PlanError as err:
+        caught = err
+
+    assert caught is not None
+    assert not isinstance(caught, PaginationLimitError)
+    assert caught.required_plan == "Business"
+
+
 # ── insiders ──────────────────────────────────────────────────────────────────
 
 @respx.mock

form4api-0.6.0/form4api/_errors.py

@@ -1,47 +0,0 @@
-from __future__ import annotations
-
-
-class Form4ApiError(Exception):
-    def __init__(self, message: str, status_code: int, error_code: str | None = None) -> None:
-        super().__init__(message)
-        self.status_code = status_code
-        self.error_code = error_code
-
-
-class AuthError(Form4ApiError):
-    def __init__(self, message: str, error_code: str | None = None) -> None:
-        super().__init__(message, 401, error_code)
-
-
-class PlanError(Form4ApiError):
-    """Raised on 402 PLAN_REQUIRED.
-
-    ``required_plan`` is the minimum plan that unlocks the endpoint (e.g.
-    ``"Business"``), ``current_plan`` is the plan the calling key is on, and
-    ``upgrade_url`` is where to upgrade. All three may be ``None`` against
-    backends older than 2026-08-05, which carried the plan names only as prose
-    inside ``message``.
-    """
-
-    def __init__(
-        self,
-        message: str,
-        required_plan: str | None = None,
-        current_plan: str | None = None,
-        upgrade_url: str | None = None,
-    ) -> None:
-        super().__init__(message, 402, "PLAN_REQUIRED")
-        self.required_plan = required_plan
-        self.current_plan = current_plan
-        self.upgrade_url = upgrade_url
-
-
-class NotFoundError(Form4ApiError):
-    def __init__(self, message: str, error_code: str | None = None) -> None:
-        super().__init__(message, 404, error_code)
-
-
-class RateLimitError(Form4ApiError):
-    def __init__(self, message: str, retry_after: int | None = None) -> None:
-        super().__init__(message, 429, "RATE_LIMIT_EXCEEDED")
-        self.retry_after = retry_after