Skip to content

docs(api): the 409 unique-constraint entry is UNIQUE_VIOLATION on the wire, not DUPLICATE_RECORD #15750

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
claude wants to merge 2 commits into
base: main
Choose a base branch
from
+7 −2
Draft

docs(api): the 409 unique-constraint entry is UNIQUE_VIOLATION on the wire, not DUPLICATE_RECORD #15750

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
447fcf9
docs(api): the 409 unique-constraint entry is UNIQUE_VIOLATION on the…
claude Sep 5, 2026
8888b38
Merge origin/main into claude/issue-15631-15632-error-docs-wire-shape
claude Sep 5, 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
9 changes: 7 additions & 2 deletions content/docs/api/error-catalog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -352,11 +352,16 @@ result set — a response indistinguishable from a successful query.
**Fix:** Delete or reassign dependent records first, then retry the delete.
**Retry:** `no_retry`

### `DUPLICATE_RECORD`
### `UNIQUE_VIOLATION`
**Cause:** A record with the same unique key already exists.
**Fix:** Update the existing record instead, or use a different unique key value.
**Retry:** `no_retry`

The engine throws `DuplicateRecordError`, whose in-process `code` is
`DUPLICATE_RECORD`; the REST door translates that envelope at the boundary, so
every route answers the wire code `UNIQUE_VIOLATION` and the in-process spelling
never crosses HTTP.

### `LOCK_CONFLICT`
**Cause:** The record is locked by another process or user.
**Fix:** Wait for the lock to be released, or contact the lock holder.
Expand Down Expand Up @@ -793,7 +798,7 @@ async function handleApiCall() {
| 401 | `authentication` | `UNAUTHENTICATED`, `EXPIRED_TOKEN`, `INVALID_CREDENTIALS` |
| 403 | `authorization` | `PERMISSION_DENIED`, `FIELD_NOT_ACCESSIBLE`, `LICENSE_REQUIRED` |
| 404 | `not_found` | `RECORD_NOT_FOUND`, `OBJECT_NOT_FOUND`, `ENDPOINT_NOT_FOUND` |
| 409 | `conflict` | `CONCURRENT_MODIFICATION`, `DUPLICATE_RECORD`, `DELETE_RESTRICTED` |
| 409 | `conflict` | `CONCURRENT_MODIFICATION`, `UNIQUE_VIOLATION`, `DELETE_RESTRICTED` |
| 422 | `validation` | `MISSING_REQUIRED_FIELD` on an absent `controlled_by_parent` master reference (see [above](#missing_required_field)) — this row is an exception to the 400 row, not a second home for the code |
| 429 | `rate_limit` | `RATE_LIMIT_EXCEEDED`, `QUOTA_EXCEEDED` |
| 500 | `server` | `INTERNAL_ERROR`, `DATABASE_ERROR` |
Expand Down
Loading