Improve insertBlocks documentation to ensure it mentions reasons the …

…action may fail silently (#50078)

docs/reference-guides/data/data-core-block-editor.md

@@ -1190,6 +1190,8 @@ _Parameters_
 
 Action that inserts a single block, optionally at a specific index respective a root block list.
 
+Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if a templateLock is active on the block list.
+
 _Parameters_
 
 -   _block_ `Object`: Block object to insert.
@@ -1206,6 +1208,8 @@ _Returns_
 
 Action that inserts an array of blocks, optionally at a specific index respective a root block list.
 
+Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if a templateLock is active on the block list.
+
 _Parameters_
 
 -   _blocks_ `Object[]`: Block objects to insert.

packages/block-editor/src/store/actions.js

@@ -543,6 +543,9 @@ export function moveBlockToPosition(
 /**
  * Action that inserts a single block, optionally at a specific index respective a root block list.
  *
+ * Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if
+ * a templateLock is active on the block list.
+ *
  * @param {Object}   block           Block object to insert.
  * @param {?number}  index           Index at which block should be inserted.
  * @param {?string}  rootClientId    Optional root client ID of block list on which to insert.
@@ -572,12 +575,16 @@ export function insertBlock(
 /**
  * Action that inserts an array of blocks, optionally at a specific index respective a root block list.
  *
+ * Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if
+ * a templateLock is active on the block list.
+ *
  * @param {Object[]}  blocks          Block objects to insert.
  * @param {?number}   index           Index at which block should be inserted.
  * @param {?string}   rootClientId    Optional root client ID of block list on which to insert.
  * @param {?boolean}  updateSelection If true block selection will be updated.  If false, block selection will not change. Defaults to true.
  * @param {0|-1|null} initialPosition Initial focus position. Setting it to null prevent focusing the inserted block.
  * @param {?Object}   meta            Optional Meta values to be passed to the action object.
+ *
  * @return {Object} Action object.
  */
 export const insertBlocks =