docs: use real quota tags; a billing limit is a 402

Capture never sends billing_limit_exceeded or billing as a per-event tag.
Product quotas drop single events in a 2xx with tags such as
llm_events_over_quota; a request over the billing limit gets a 402 with
no per-event results.

Author: eli-r-ph

docs/migration-7.x-to-8.0.md

@@ -57,15 +57,16 @@ Posthog("<api_key>", host="https://us.i.posthog.com", debug=True)
 ## Errors and `on_error`
 
 Capture v1 returns a result for every event, even when the request succeeds.
-An event can be dropped, for example by billing limits or quotas, inside a 2xx response.
+An event can be dropped inside a 2xx response, for example when it is over a product quota.
 8.0 reports those events as failures.
+When the whole request is over the billing limit, capture returns a `402` with no per-event results instead.
 
 - Every capture failure is a `CaptureError`. It has these fields:
   - `status`: the HTTP status, or `0` when the request never got a response
   - `endpoint`, `request_id` and `attempts`
   - `drops` and `retry_exhausted`: the uuids that were dropped or ran out of retries
   - `event_results`: a `CaptureEventResult(result, details)` for each uuid, from `posthog.capture_send`
-  - `verdict_summary()`: counts such as `drop/billing=1, retry/not_persisted=1`
+  - `verdict_summary()`: counts such as `drop/llm_events_over_quota=1, retry/not_persisted=1`
 - `on_error(error, batch)` receives every failure, including in `sync_mode` and from `AsyncPosthog.capture_immediate`.
 - Without `on_error`, the SDK logs one line per failed batch, for example `2 event(s) not persisted by /i/v1/analytics/events: ...`. The line never contains event content or the server's response text.
 - In `sync_mode`, a failed `capture()` calls `on_error` and returns `None`. With `debug=True` it calls `on_error` and then re-raises the error.

posthog/capture_send.py

@@ -91,7 +91,7 @@ class CaptureEventResult:
 
     ``result`` is ``ok``, ``warning``, ``drop`` or ``retry``, or a value newer
     than this SDK, which counts as success. ``details`` is the server's reason
-    tag, such as ``billing_limit_exceeded``.
+    tag, such as ``llm_events_over_quota``.
     """
 
     result: Optional[str]
@@ -156,7 +156,7 @@ def __init__(
 
     def verdict_summary(self) -> str:
         """Count the undelivered events by verdict and reason, for example
-        ``drop/billing_limit_exceeded=2, retry/not_persisted=1``.
+        ``drop/llm_events_over_quota=2, retry/not_persisted=1``.
 
         Counts the events in ``drops`` and ``retry_exhausted``: events the
         server dropped, and events still pending retry after the last 2xx

posthog/test/test_capture_send.py

@@ -366,13 +366,15 @@ def test_drop_accumulated_across_attempts_surfaces_on_later_success(self) -> Non
         stub, exc = self._run_expecting_error(
             batch,
             [
-                _results_response({"u-drop": ("drop", "billing"), "u-retry": "retry"}),
+                _results_response(
+                    {"u-drop": ("drop", "llm_events_over_quota"), "u-retry": "retry"}
+                ),
                 _results_response({"u-retry": "ok"}),
             ],
         )
         self.assertEqual(len(stub.calls), 2)
         self.assertEqual(stub.calls[1]["uuids"], ["u-retry"])  # only retry resent
-        self.assertEqual(exc.drops, [("u-drop", "billing")])
+        self.assertEqual(exc.drops, [("u-drop", "llm_events_over_quota")])
         self.assertEqual(exc.retry_exhausted, [])
 
     def test_retry_exhausted_raises_with_uuids(self) -> None:
@@ -394,7 +396,7 @@ def test_retry_exhausted_carries_earlier_drops(self) -> None:
                 _results_response(
                     {
                         "u-ok": "ok",
-                        "u-drop": ("drop", "billing"),
+                        "u-drop": ("drop", "llm_events_over_quota"),
                         "u-retry": "retry",
                     }
                 ),
@@ -405,16 +407,18 @@ def test_retry_exhausted_carries_earlier_drops(self) -> None:
         self.assertEqual(len(stub.calls), 2)
         self.assertEqual(exc.endpoint, _CAPTURE_V1_PATH)
         self.assertEqual(exc.retry_exhausted, ["u-retry"])
-        self.assertEqual(exc.drops, [("u-drop", "billing")])
+        self.assertEqual(exc.drops, [("u-drop", "llm_events_over_quota")])
         self.assertEqual(
             exc.event_results,
             {
                 "u-ok": CaptureEventResult("ok"),
-                "u-drop": CaptureEventResult("drop", "billing"),
+                "u-drop": CaptureEventResult("drop", "llm_events_over_quota"),
                 "u-retry": CaptureEventResult("retry", "not_persisted"),
             },
         )
-        self.assertEqual(exc.verdict_summary(), "drop/billing=1, retry/not_persisted=1")
+        self.assertEqual(
+            exc.verdict_summary(), "drop/llm_events_over_quota=1, retry/not_persisted=1"
+        )
 
     @parameterized.expand(
         [
@@ -432,11 +436,11 @@ def test_results_match_non_canonical_uuid(self, _name, sent_uuid) -> None:
             [_msg(sent_uuid)],
             [
                 _results_response({canonical: "retry"}),
-                _results_response({canonical: ("drop", "billing")}),
+                _results_response({canonical: ("drop", "llm_events_over_quota")}),
             ],
         )
         self.assertEqual(len(stub.calls), 2)
-        self.assertEqual(exc.drops, [(canonical, "billing")])
+        self.assertEqual(exc.drops, [(canonical, "llm_events_over_quota")])
 
     def test_malformed_2xx_is_terminal(self) -> None:
         stub, exc = self._run_expecting_error(
@@ -536,17 +540,17 @@ class TestCaptureLossMessage(unittest.TestCase):
                     200,
                     "2 event(s) not delivered",
                     endpoint=_CAPTURE_V1_PATH,
-                    drops=[("u-drop", "billing")],
+                    drops=[("u-drop", "llm_events_over_quota")],
                     retry_exhausted=["u-retry"],
                     event_results={
                         "u-ok": CaptureEventResult("ok"),
-                        "u-drop": CaptureEventResult("drop", "billing"),
+                        "u-drop": CaptureEventResult("drop", "llm_events_over_quota"),
                         "u-retry": CaptureEventResult("retry", "not_persisted"),
                     },
                 ),
                 3,
                 "2 event(s) not persisted by /i/v1/analytics/events: 1 dropped, "
-                "1 out of retries (drop/billing=1, retry/not_persisted=1)",
+                "1 out of retries (drop/llm_events_over_quota=1, retry/not_persisted=1)",
             ),
             (
                 "request_failure_after_partial_success",