diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx
index 31a034c402..71bdf34979 100644
--- a/content/docs/api/error-catalog.mdx
+++ b/content/docs/api/error-catalog.mdx
@@ -215,13 +215,39 @@ key runs no write-time check on any field type, so editing it changes nothing.
 **Retry:** `no_retry`
 
 ### `VALUE_TOO_LONG`
-**Cause:** String value exceeds the field's `maxLength` constraint.  
-**Fix:** Truncate the value to the maximum allowed length.  
+**Cause:** Reserved for a string value longer than its declared maximum. **No route emits it
+today.** A length miss is refused as a *field-level* `max_length` entry instead, and where that
+entry rides depends on what was written:
+
+- **a record write** (a string over a field's `maxLength`) and **a request body a route parses
+  with Zod** answer `400 VALIDATION_FAILED` with the entry in `fields[]` — top-level on the
+  `/data` routes, under `details` when the runtime dispatcher serves it (see
+  [`VALIDATION_FAILED`](#validation_failed)); on a record write its `constraint` carries
+  `maxLength` and the `actual` length;
+- **a settings write** (a value over its declared maximum) answers `400 SETTINGS_VALIDATION`
+  with the entry in `details.fields[]`.
+
+**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code`
+`max_length`, or on `SETTINGS_VALIDATION` + `details.fields[].code` `max_length` for a settings write,
+and shorten the value to fit the declared maximum.  
 **Retry:** `no_retry`
 
 ### `VALUE_TOO_SHORT`
-**Cause:** String value is below the field's `minLength` constraint.  
-**Fix:** Provide a longer value that meets the minimum length requirement.  
+**Cause:** Reserved for a string value shorter than its declared minimum. **No route emits it
+today.** A length miss is refused as a *field-level* `min_length` entry instead, and where that
+entry rides depends on what was written:
+
+- **a record write** (a string under a field's `minLength`) and **a request body a route parses
+  with Zod** answer `400 VALIDATION_FAILED` with the entry in `fields[]` — top-level on the
+  `/data` routes, under `details` when the runtime dispatcher serves it (see
+  [`VALIDATION_FAILED`](#validation_failed)); on a record write its `constraint` carries
+  `minLength` and the `actual` length;
+- **a settings write** (a value under its declared minimum) answers `400 SETTINGS_VALIDATION`
+  with the entry in `details.fields[]`.
+
+**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code`
+`min_length`, or on `SETTINGS_VALIDATION` + `details.fields[].code` `min_length` for a settings write,
+and lengthen the value to meet the declared minimum.  
 **Retry:** `no_retry`
 
 ### `VALUE_OUT_OF_RANGE`