docs: Add more info about free users (#2150)

Author: patrikbraborec

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,15 @@ async def main():
 
 </TabItem>
 </Tabs>
+
+## Communicate limitations
+
+If your Actor has specific limitations for users on the Apify free plan (e.g., restricted features, limited results), communicate these clearly to avoid confusion.
+
+- Status messages: Use `Actor.setStatusMessage` or `Actor.exit` message to explain why a run finished early or failed (e.g., "This Actor has a special daily limit for free plan users. This was set by the Actor developer, not Apify. Upgrade to continue.").
+- Provide clear error messages: Don't return generic system errors or fail the run in a way that looks like a platform issue. This frustrates users and makes troubleshooting difficult.
+  - Wrong: API usage is limited to 10 results
+  - Right: This Actor only allows up to 10 results for free users. Upgrade to a paid plan to receive unlimited results.
+- Documentation: Clearly state any limitations in your Actor's `README` and input schema descriptions so users know what to expect before running the Actor.
+  - General restrictions (like limiting the number of results) must be explained in the top-level input schema description that renders above the input editor UI.
+  - Feature-specific limitations must be included in the title of an input field. The title must include explanation in parenthesis such as `(paying users only)` or `(limited for free users)`. E.g. `Max comments (paying users only)`.

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

@@ -29,18 +29,18 @@ 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`) |
-
-## Setting up monetization
+| 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`) |
+
+## Set up monetization
 
 Navigate to your [Actor page](https://console.apify.com/actors?tab=my) in Apify Console, choose the Actor that you want to monetize, and select the Publication tab.
 ![Monetization section](../images/monetization-section.png)
@@ -61,7 +61,7 @@ Follow the monetization wizard to configure your pricing model.
 </TabItem>
 </Tabs>
 
-### Changing monetization
+### Change monetization
 
 You can change the monetization setting of your Actor by using the same wizard as for the setup in the **Monetization** section of your Actor's **Publication** tab.
 
@@ -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.
 
+## Handle 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, don't 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**.
@@ -115,7 +123,7 @@ The analytics dashboard allows you to select specific Actors and view key metric
 
 All metrics can be exported as JSON for custom analysis and reporting.
 
-## Promoting your Actor
+## Promote your Actor
 
 Create search-engine-optimized descriptions and README files to improve search engine visibility. Share your Actor on multiple channels: