docs: Explain how to correctly terminate PPE Actors (#568)

Author: janbuchar

docs/02_concepts/08_pay_per_event.mdx

@@ -6,6 +6,7 @@ description: Monetize your Actors using the pay-per-event pricing model
 
 import ActorChargeSource from '!!raw-loader!./code/actor_charge.ts';
 import ConditionalActorChargeSource from '!!raw-loader!./code/conditional_actor_charge.ts';
+import ChargeLimitCheckSource from '!!raw-loader!./code/charge_limit_check.ts';
 import ApiLink from '@site/src/components/ApiLink';
 import CodeBlock from '@theme/CodeBlock';
 
@@ -29,6 +30,20 @@ Then you just push your code to Apify and that's it! The SDK will even keep trac
 
 If you need finer control over charging, you can access call <ApiLink to="class/Actor#getChargingManager">`Actor.getChargingManager()`</ApiLink> to access the <ApiLink to="class/ChargingManager">`ChargingManager`</ApiLink>, which can provide more detailed information - for example how many events of each type can be charged before reaching the configured limit.
 
+### Handling the charge limit
+
+While the SDK automatically prevents overcharging by limiting how many events are charged and how many items are pushed, **it does not stop your Actor from running**. When the charge limit is reached, `Actor.charge` and `Actor.pushData` will silently stop charging and pushing data, but your Actor will keep running — potentially doing expensive work (scraping pages, calling APIs) for no purpose. This means your Actor may never terminate on its own if you don't check the charge limit yourself.
+
+To avoid this, you should check the `eventChargeLimitReached` field in the result returned by <ApiLink to="class/Actor#charge">`Actor.charge`</ApiLink> or `Actor.pushData` and stop your Actor when the limit is reached. You can also use the `chargeableWithinLimit` field from the result to plan ahead — it tells you how many events of each type can still be charged within the remaining budget.
+
+<CodeBlock language="typescript">{ChargeLimitCheckSource}</CodeBlock>
+
+Alternatively, you can periodically check the remaining budget via <ApiLink to="class/Actor#getChargingManager">`Actor.getChargingManager()`</ApiLink> instead of inspecting every `ChargeResult`. This can be useful when charging happens in multiple places across your code, or when using a crawler where you don't directly control the main loop.
+
+:::caution
+Always check the charge limit in your Actor, whether through `ChargeResult` return values or the `ChargingManager`. Without this check, your Actor will continue running and consuming platform resources after the budget is exhausted, producing no output.
+:::
+
 ## Transitioning from a different pricing model
 
 When you plan to start using the pay-per-event pricing model for an Actor that is already monetized with a different pricing model, your source code will need support both pricing models during the transition period enforced by the Apify platform. Arguably the most frequent case is the transition from the pay-per-result model which utilizes the `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable to prevent returning unpaid dataset items. The following is an example how to handle such scenarios. The key part is the <ApiLink to="class/ChargingManager#getPricingInfo">`ChargingManager.getPricingInfo`</ApiLink> method which returns information about the current pricing model.

docs/02_concepts/code/charge_limit_check.ts

@@ -0,0 +1,29 @@
+import { Actor } from 'apify';
+
+await Actor.init();
+
+const urls = [
+    'https://example.com/1',
+    'https://example.com/2',
+    'https://example.com/3',
+];
+
+for (const url of urls) {
+    // Do some expensive work (e.g. scraping, API calls)
+    const result = { url, data: `Scraped data from ${url}` };
+
+    // highlight-start
+    // pushData returns a ChargeResult - check it to know if the budget ran out
+    const { eventChargeLimitReached } = await Actor.pushData(
+        result,
+        'result-item',
+    );
+
+    if (eventChargeLimitReached) {
+        console.log('Charge limit reached, stopping the Actor');
+        break;
+    }
+    // highlight-end
+}
+
+await Actor.exit();