Merge pull request #9516 from circleci/add-error-message-for-retention

Add error documentation for job retention configuration

Author: ahmedwab

docs/reference/modules/ROOT/pages/configuration-reference.adoc

@@ -494,8 +494,6 @@ jobs:
 
 Configure job retention periods to control how long job data is kept. Job retention specifically controls cache retention at the job level. This setting can be configured from 1 day to 15 days using string values (for example, "1d", "7d", "15d"). Job retention reduces the organization-level retention from the default by automatically removing cache data after the specified period.
 
-For more information on cache retention, see the xref:guides:optimize:persist-data.adoc#custom-storage-usage[Persisting data overview] page.
-
 *Example:*
 
 [source,yaml]
@@ -514,6 +512,48 @@ jobs:
       - run: npm test
 ----
 
+For more information on cache retention, see the xref:guides:optimize:persist-data.adoc#custom-storage-usage[Persisting data overview] page.
+
+[#retention-errors]
+===== Common errors
+
+When configuring job retention, you may encounter the following validation errors:
+
+* **Invalid time format**: The retention period must use the format `^([1-9]|[12][0-9]|30)d$` (1-30 days with "d" suffix). For example, use `"7d"` instead of `"12h"` or `"1w"`.
+
+* **Incorrect data type**: The `retention` key expects a map with `caches` as a string value, not a direct string.
+
+*Examples:*
+
+.Incorrect - direct string value
+[source,yaml]
+----
+# Incorrect - direct string value
+jobs:
+  say-hello:
+    retention: "12h"  # Error: expected type: String, found: Mapping
+----
+
+.Incorrect - invalid time format
+[source,yaml]
+----
+#Incorrect - invalid time format
+jobs:
+  say-hello:
+    retention:
+      caches: "12h"  # Error: does not match pattern ^([1-9]|[12][0-9]|30)d$
+----
+
+.Correct format
+[source,yaml]
+----
+# Correct format
+jobs:
+  say-hello:
+    retention:
+      caches: "7d"   # Valid: 7 days
+----
+
 '''
 
 [#parallelism]