diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc
index dbc7d5ba7b..9e832e9974 100644
--- a/docs/detections/api/rules/rules-api-create.asciidoc
+++ b/docs/detections/api/rules/rules-api-create.asciidoc
@@ -280,9 +280,11 @@ means the rule runs every hour. Defaults to `5m` (5 minutes).
 
 |license |String |The rule's license.
 
-|max_signals |Integer |Maximum number of alerts the rule can create during a
+|max_signals |Integer a|Maximum number of alerts the rule can create during a
 single execution. Defaults to `100`.
 
+*NOTE*: To avoid rule failures, do not set the `max_signals` value higher than the value of {kibana-ref}/alert-action-settings-kb.html#alert-settings[`xpack.alerting.rules.run.alerts.max`]. 
+
 |meta |Object a|Placeholder for metadata about the rule.
 
 *NOTE*: This field is overwritten when you save changes to the rule's settings.