From ab8b19ea0f3312aef1bf0bfc5e94c18265b3be3f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 16:57:15 +0000 Subject: [PATCH 1/2] docs(error-catalog): VALUE_TOO_LONG / VALUE_TOO_SHORT name the field-level codes that really arrive No producer emits either top-level code; a length miss is refused inside VALIDATION_FAILED with fields[].code max_length / min_length (record validator, settings values, Zod-parsed request bodies). Both entries now say so and tell clients to branch on VALIDATION_FAILED + fields[].code, mirroring the INVALID_FORMAT entry. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv --- content/docs/api/error-catalog.mdx | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx index 31a034c402..6a0e5d9c5d 100644 --- a/content/docs/api/error-catalog.mdx +++ b/content/docs/api/error-catalog.mdx @@ -215,13 +215,25 @@ 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 string over a field's `maxLength` is refused as a *field-level* failure inside +`VALIDATION_FAILED` instead, with `fields[].code` `max_length`; on a record write that entry's +`constraint` carries `maxLength` and the `actual` length. A settings value over its declared +maximum, and a string in a request body a route parses with Zod, also answer field-level +`max_length`. +**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code` +`max_length`, 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 string under a field's `minLength` is refused as a *field-level* failure inside +`VALIDATION_FAILED` instead, with `fields[].code` `min_length`; on a record write that entry's +`constraint` carries `minLength` and the `actual` length. A settings value under its declared +minimum, and a string in a request body a route parses with Zod, also answer field-level +`min_length`. +**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code` +`min_length`, and lengthen the value to meet the declared minimum. **Retry:** `no_retry` ### `VALUE_OUT_OF_RANGE` From 37431df1c5447e898bff3befe718aa9028ff0698 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 17:13:58 +0000 Subject: [PATCH 2/2] docs(error-catalog): name where each length-miss path puts its field entry A settings write refuses a length miss as 400 SETTINGS_VALIDATION with the entry in details.fields[], not VALIDATION_FAILED; record writes and Zod-parsed bodies answer VALIDATION_FAILED with the entry in fields[] (top-level on /data, under details via the runtime dispatcher). Both entries and their Fix lines now name both envelopes. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv --- content/docs/api/error-catalog.mdx | 38 ++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx index 6a0e5d9c5d..71bdf34979 100644 --- a/content/docs/api/error-catalog.mdx +++ b/content/docs/api/error-catalog.mdx @@ -216,24 +216,38 @@ key runs no write-time check on any field type, so editing it changes nothing. ### `VALUE_TOO_LONG` **Cause:** Reserved for a string value longer than its declared maximum. **No route emits it -today.** A string over a field's `maxLength` is refused as a *field-level* failure inside -`VALIDATION_FAILED` instead, with `fields[].code` `max_length`; on a record write that entry's -`constraint` carries `maxLength` and the `actual` length. A settings value over its declared -maximum, and a string in a request body a route parses with Zod, also answer field-level -`max_length`. +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`, and shorten the value to fit the declared maximum. +`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:** Reserved for a string value shorter than its declared minimum. **No route emits it -today.** A string under a field's `minLength` is refused as a *field-level* failure inside -`VALIDATION_FAILED` instead, with `fields[].code` `min_length`; on a record write that entry's -`constraint` carries `minLength` and the `actual` length. A settings value under its declared -minimum, and a string in a request body a route parses with Zod, also answer field-level -`min_length`. +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`, and lengthen the value to meet the declared minimum. +`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`