docs: Custom error messages in the input schema (#2121)

Document custom error messages in the input schema, introduced by
apify/apify-shared-js#567 (based on the
specification [here](apify/apify-shared-js#556))

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Documents custom validation error messages for input schema and links
them from the spec and index.
> 
> - **Docs**:
> - Add new guide `input_schema/custom_error_messages.md` explaining
`errorMessage` usage, supported validation keywords, nesting, and best
practices.
> - Update `input_schema/specification.md` to include `errorMessage` in
input field properties table with link to the new page.
> - Update `input_schema/index.md` to reference the spec, secrets, and
new custom error messages guide.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
19d0412. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Marcel Rebro <[email protected]>

Author: mfori

sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md

@@ -0,0 +1,105 @@
+---
+title: Custom error messages
+description: Learn how to define custom error messages for input validation in your Actor's input schema. Make validation feedback clearer and more user-friendly.
+slug: /actors/development/actor-definition/input-schema/custom-error-messages
+---
+
+**Learn how to define custom error messages for input validation in your Actor's input schema. Make validation feedback clearer and more user-friendly.**
+
+---
+
+When an input fails validation against an Actor's input schema, the resulting errors are processed and displayed to the user. By default, these messages are generic and may not clearly explain what the validation rule actually means.
+
+Custom error messages allow Actor developers to define tailored feedback messages for input validation errors, making it easier for users to understand what is required and improving overall usability.
+
+## The problem with generic error messages
+
+Some validation rules have a specific purpose that generic error messages don't explain well. For example, consider the following input field using the `pattern` validation keyword:
+
+```json
+{
+  "title": "Email address",
+  "type": "string",
+  "description": "Your email address",
+  "editor": "textfield",
+  "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+}
+```
+
+Input that doesn't satisfy the pattern will produce an error message like:
+
+```text
+Field "email" should match pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$".
+```
+
+However, a message such as the following would be much more understandable for the user:
+
+```text
+Field "email" must be a valid email address.
+```
+
+## Custom error messages for input fields
+
+Each property in the [input schema](./index.md) can include an `errorMessage` field that defines a custom error message to be displayed when validation of that field fails.
+
+The `errorMessage` must be an object that maps *validation keywords* (e.g., `type`, `pattern`, `minLength`) to their respective custom messages.
+
+```json title="Email input with custom error messages"
+{
+  "title": "Email address",
+  "type": "string",
+  "description": "Your email address",
+  "editor": "textfield",
+  "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+  "errorMessage": {
+    "type": "Email must be a string",
+    "pattern": "Email must be a valid email address"
+  }
+}
+```
+
+If a validation error occurs for a keyword that is not listed in the `errorMessage` object, the system will fall back to the default error message.
+
+:::note User-friendly messages
+
+Custom error messages are especially useful for complex validation rules like regular expressions, where the default error message would show the entire pattern, which is not user-friendly. Refer to the [best practices](#best-practices) for more guidance.
+
+:::
+
+### Supported validation keywords
+
+You can define custom error messages for any validation keyword supported by the [input schema](./index.md), including:
+
+| Type               | Supported validation keywords                                               |
+|--------------------|-----------------------------------------------------------------------------|
+| `string`           | `type`, `pattern`, `minLength`, `maxLength`, `enum`                         |
+| `number`/`integer` | `type`, `minimum`, `maximum`                                                |
+| `boolean`          | `type`                                                                      |
+| `array`            | `type`, `minItems`, `maxItems`, `uniqueItems`, `patternKey`, `patternValue` |
+| `object`           | `type`, `minProperties`, `maxProperties`, `patternKey`, `patternValue`      |
+
+#### Nested properties
+
+It's possible to define custom error messages in sub-properties as well. For objects with nested properties, you can define error messages at any level of nesting:
+
+```json
+{
+  "title": "User",
+  "type": "object",
+  "description": "Provide user details",
+  "editor": "schemaBased",
+  "properties": {
+    "email": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+      "errorMessage": {
+        "pattern": "Please enter a valid email address"
+      }
+    }
+  }
+}
+```
+
+## Best practices
+
+Custom error messages can be useful in specific cases, but they aren't always necessary. In most situations, the default validation messages are clear enough and ensure consistency across the platform. Use custom messages only when they meaningfully improve clarity—for example, when the default message would expose an unreadable regular expression or fail to explain a non-obvious requirement.

sources/platform/actors/development/actor_definition/input_schema/index.md

@@ -78,4 +78,4 @@ The actual input object passed from the autogenerated input UI to the Actor then
 }
 ```
 
-Next, let's take a look at [input schema specification](./specification.md), and the possibility of using input schema to enable users to pass [secrets](./secret_input.md).
+Next, let's take a look at [input schema specification](./specification.md), the possibility of using input schema to enable users to pass [secrets](./secret_input.md), and how to define [custom error messages](./custom_error_messages.md) for input validation.

sources/platform/actors/development/actor_definition/input_schema/specification.md

@@ -130,6 +130,7 @@ Each field of your input is described under its key in the `inputSchema.properti
 | `default` | Must match `type` property. | No | Default value that will be <br/>used when no value is provided. |
 | `prefill` | Must match `type` property. | No | Value that will be prefilled <br/>in the Actor input interface. |
 | `example` | Must match `type` property. | No | Sample value of this field <br/>for the Actor to be displayed when <br/>Actor is published in Apify Store. |
+| `errorMessage` | Object | No | Custom error messages for validation keywords. <br/>See [custom error messages](./custom_error_messages.md) <br/>for more details. |
 | `sectionCaption` | String | No | If this property is set, <br/>then all fields following this field <br/>(this field included) will be separated <br/>into a collapsible section <br/>with the value set as its caption. <br/>The section ends at the last field <br/>or the next field which has the <br/> `sectionCaption` property set. |
 | `sectionDescription` | String | No | If the `sectionCaption` property is set, <br/>then you can use this property to <br/>provide additional description to the section. <br/>The description will be visible right under <br/>the caption when the section is open. |