docs: Add more info about free users

sources/platform/actors/development/programming_interface/status_messages.md

@@ -15,7 +15,7 @@ import TabItem from '@theme/TabItem';
 Each Actor run has a status, represented by the `status` field. The following table describes the possible values:
 
 |Status|Type|Description|
-|--- |--- |--- |
+|---|---|---|
 |`READY`|initial|Started but not allocated to any worker yet|
 |`RUNNING`|transitional|Executing on a worker|
 |`SUCCEEDED`|terminal|Finished successfully|
@@ -76,3 +76,11 @@ async def main():
 
 </TabItem>
 </Tabs>
+
+## Communicating limitations
+
+If your Actor has specific limitations for users on the Apify free plan (e.g., restricted features, limited results), it is crucial to communicate these clearly to avoid confusion.
+
+- Status messages: Use `setStatusMessage` or the exit message to explain why a run finished early or failed (e.g., "Daily limit for free plan reached. Upgrade to continue.").
+- Avoid false errors: Do not return generic system errors or fail the run in a way that looks like a platform issue. This frustrates users and makes troubleshooting difficult.
+- Documentation: Clearly state any limitations in your Actor's `README` and input schema descriptions so users know what to expect before running the Actor.

sources/platform/actors/publishing/monetize/index.mdx

@@ -29,16 +29,16 @@ For a detailed comparison of pricing models from the perspective of your users,
 
 The following table compares the two main pricing models available for monetizing your Actors:
 
-| Feature/Category         | Rental                | Pay-per-result (PPR)         | Pay-per-event (PPE)           |
-|-------------------------|-------------------------------|-------------------------------|-------------------------------|
-| Revenue scalability     | Capped at monthly fee         | Unlimited, scales with usage  | Unlimited, scales with usage  |
-| AI/MCP compatibility    | ❌ Not compatible             | ✅ Fully compatible           | ✅ Fully compatible           |
-| User cost predictability| Unpredictable (rental + usage)    | Predictable    | Predictable    |
-| Store discounts         | ❌ Single price only          | ✅ Store discounts available  | ✅ Store discounts available  |
-| Marketing boost         | Standard visibility           | Standard visibility           | Priority store placement      |
-| Commission opportunities| Standard 20%                  | Standard 20%                  | Standard 20%       |
-| Custom event billing    | Not available                 | Not available                 | ✅ Charge for any event       |
-| Per-result billing      | Not available                 | ✅ Charge per dataset item    | Optional (via event; automatic via `apify-default-dataset-item`) |
+| Feature/Category         | Rental                         | Pay-per-result (PPR)          | Pay-per-event (PPE)                                              |
+|--------------------------|--------------------------------|-------------------------------|------------------------------------------------------------------|
+| Revenue scalability      | Capped at monthly fee          | Unlimited, scales with usage  | Unlimited, scales with usage                                     |
+| AI/MCP compatibility     | ❌ Not compatible              | ✅ Fully compatible           | ✅ Fully compatible                                              |
+| User cost predictability | Unpredictable (rental + usage) | Predictable                   | Predictable                                                      |
+| Store discounts          | ❌ Single price only           | ✅ Store discounts available  | ✅ Store discounts available                                     |
+| Marketing boost          | Standard visibility            | Standard visibility           | Priority store placement                                         |
+| Commission opportunities | Standard 20%                   | Standard 20%                  | Standard 20%                                                     |
+| Custom event billing     | Not available                  | Not available                 | ✅ Charge for any event                                          |
+| Per-result billing       | Not available                  | ✅ Charge per dataset item    | Optional (via event; automatic via `apify-default-dataset-item`) |
 
 ## Setting up monetization
 
@@ -100,6 +100,14 @@ If no action is taken, the payout will be automatically approved on the 14th, wi
 
 If the monthly profit does not meet these thresholds, as per our [Terms & Conditions](https://apify.com/store-terms-and-conditions), the funds will roll over to the next month until the threshold is reached.
 
+## Handling free users
+
+When monetizing your Actor, you might want to limit features or usage for users on the Apify free plan. If you choose to do this, you **must** handle it transparently:
+
+- Communicate upfront: Clearly state any limitations in your Actor's `README` and input schema. Users should know about restrictions _before_ they run the Actor.
+- Graceful exits: If a free user hits a limit, do not crash the Actor or return a system error. Instead, exit gracefully with a clear [status message](/platform/actors/development/programming-interface/status-messages#communicating-limitations) explaining the limit (e.g., "Free tier limit reached").
+- Avoid confusion: Never make a policy restriction look like a bug or platform error.
+
 ## Actor analytics
 
 Monitor your Actors' performance through the [Actor Analytics](https://console.apify.com/actors/insights/analytics) dashboard under **Development > Insights > Analytics**.