Skip to content

docs(error-catalog): INVALID_FORMAT names what really checks a value (field type or a format rule) #19878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
objectstack-fleet wants to merge 2 commits into
base: main
Choose a base branch
from
+16 −3
Draft

docs(error-catalog): INVALID_FORMAT names what really checks a value (field type or a format rule) #19878

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d56a2a7
docs(error-catalog): INVALID_FORMAT names what really checks a value'…
claude Sep 23, 2026
40758ef
docs(error-catalog): say the field format key runs no check on any type
claude Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions content/docs/api/error-catalog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
]
}
```
Expand Down Expand Up @@ -197,8 +197,21 @@ rather than deriving it from the table at the end of this page.
</Callout>

### `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 runs no write-time check on any field type, so editing it changes nothing.
**Retry:** `no_retry`

### `VALUE_TOO_LONG`
Expand Down
Loading