Skip to content

Commit d56a2a7

Browse files
committed
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 <noreply@anthropic.com>
1 parent 2bbb462 commit d56a2a7

1 file changed

Lines changed: 16 additions & 3 deletions

File tree

‎content/docs/api/error-catalog.mdx‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ entry's cross-reference sentence so the in-process one stays findable.
6969
"httpStatus": 400,
7070
"retryable": false,
7171
"fields": [
72-
{ "field": "email", "message": "Invalid email format", "code": "invalid_format" }
72+
{ "field": "email", "message": "Invalid email format", "code": "invalid_email" }
7373
]
7474
}
7575
```
@@ -197,8 +197,21 @@ rather than deriving it from the table at the end of this page.
197197
</Callout>
198198

199199
### `INVALID_FORMAT`
200-
**Cause:** Field value does not match the expected format (e.g., invalid email, wrong date format).
201-
**Fix:** Ensure the value matches the field's `format` constraint or built-in type validation.
200+
**Cause:** Reserved for a value that does not match an expected format. **No route emits it
201+
today.** A malformed value is refused as a *field-level* failure inside `VALIDATION_FAILED`
202+
instead, and its `fields[].code` names what checked it:
203+
204+
- **the field's `type`** — an `email`, `url` or `phone` field runs a built-in shape check keyed
205+
on `type` itself and answers `invalid_email` / `invalid_url` / `invalid_phone`; a value a
206+
`date`, `datetime` or `time` field cannot parse answers `invalid_date` / `invalid_time`;
207+
- **a [`format` validation rule](/docs/data-modeling/validation#format-validation)** — its
208+
`regex`, or its named `format` (`email` | `url` | `phone` | `json`) — answers `invalid_format`.
209+
210+
A value that misses a declared `pattern` outside record metadata (a settings value, a request
211+
body a route parses with Zod) also answers field-level `invalid_format`.
212+
**Fix:** Do not branch on this code; branch on `VALIDATION_FAILED` + `fields[].code`. To change
213+
what a field accepts, change its `type` or the `format` validation rule — a field-level `format`
214+
key is a display hint the server never checks, so editing it changes nothing.
202215
**Retry:** `no_retry`
203216

204217
### `VALUE_TOO_LONG`

0 commit comments

Comments
 (0)