From d56a2a7f075f64b80ed6025502e2ca7f97c2ea76 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 13:59:16 +0000 Subject: [PATCH 1/2] docs(error-catalog): INVALID_FORMAT names what really checks a value's format The INVALID_FORMAT entry told authors to fix the failure by matching "the field's `format` constraint", but the write-time record validator never reads a field-level `format` key: its email / url / phone shape checks key on the field `type`, and a `format` validation rule (a different key) answers field-level `invalid_format`. No route emits the top-level INVALID_FORMAT at all, so the entry now says so and points at VALIDATION_FAILED + fields[].code, the same shape the INVALID_REFERENCE entry already uses. The VALIDATION_ERROR example's email entry now carries `invalid_email`, the code the Zod issue mapper actually produces for an email-format miss. Claude-Session: https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv Co-authored-by: Claude --- content/docs/api/error-catalog.mdx | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx index e7fdf496d6a..74d598033fd 100644 --- a/content/docs/api/error-catalog.mdx +++ b/content/docs/api/error-catalog.mdx @@ -69,7 +69,7 @@ entry's cross-reference sentence so the in-process one stays findable. "httpStatus": 400, "retryable": false, "fields": [ - { "field": "email", "message": "Invalid email format", "code": "invalid_format" } + { "field": "email", "message": "Invalid email format", "code": "invalid_email" } ] } ``` @@ -197,8 +197,21 @@ rather than deriving it from the table at the end of this page. ### `INVALID_FORMAT` -**Cause:** Field value does not match the expected format (e.g., invalid email, wrong date format). -**Fix:** Ensure the value matches the field's `format` constraint or built-in type validation. +**Cause:** Reserved for a value that does not match an expected format. **No route emits it +today.** A malformed value is refused as a *field-level* failure inside `VALIDATION_FAILED` +instead, and its `fields[].code` names what checked it: + +- **the field's `type`** — an `email`, `url` or `phone` field runs a built-in shape check keyed + on `type` itself and answers `invalid_email` / `invalid_url` / `invalid_phone`; a value a + `date`, `datetime` or `time` field cannot parse answers `invalid_date` / `invalid_time`; +- **a [`format` validation rule](/docs/data-modeling/validation#format-validation)** — its + `regex`, or its named `format` (`email` | `url` | `phone` | `json`) — answers `invalid_format`. + +A value that misses a declared `pattern` outside record metadata (a settings value, a request +body a route parses with Zod) also answers field-level `invalid_format`. +**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code`. To change +what a field accepts, change its `type` or the `format` validation rule — a field-level `format` +key is a display hint the server never checks, so editing it changes nothing. **Retry:** `no_retry` ### `VALUE_TOO_LONG` From 40758ef85a4dc1a7b894bba1530f0e90ea90a57b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 14:28:39 +0000 Subject: [PATCH 2/2] docs(error-catalog): say the field format key runs no check on any type Outside `autonumber` the key is a display hint and on `autonumber` it is the record-number pattern, so 'a display hint the server never checks' was only right for most types; what holds for every type is that no write-time check reads it. Claude-Session: https://claude.ai/code/session_01VDtqoecgES7ScQYGbFVDRv Co-authored-by: Claude --- content/docs/api/error-catalog.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx index 74d598033fd..31a034c4026 100644 --- a/content/docs/api/error-catalog.mdx +++ b/content/docs/api/error-catalog.mdx @@ -211,7 +211,7 @@ A value that misses a declared `pattern` outside record metadata (a settings val body a route parses with Zod) also answers field-level `invalid_format`. **Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code`. To change what a field accepts, change its `type` or the `format` validation rule — a field-level `format` -key is a display hint the server never checks, so editing it changes nothing. +key runs no write-time check on any field type, so editing it changes nothing. **Retry:** `no_retry` ### `VALUE_TOO_LONG`