Observation recorded while implementing #14723 (maintainer ruling A: a unique-constraint refusal has ONE wire spelling on every route, UNIQUE_VIOLATION; the engine's thrown DuplicateRecordError.code stays DUPLICATE_RECORD in-process). Filed unassigned; not addressed by the #14723 PR, whose surface is code, pins and changesets.
What the page says
content/docs/protocol/kernel/error-handling.mdx, section ## Error Codes / ### Resource Errors, at line 349 on origin/main 2ed6be649:
#### DUPLICATE_RECORD — "HTTP Status: 409", "Meaning: Resource with unique constraint already exists", with an example HTTP body whose error.code is "DUPLICATE_RECORD" (and a details object carrying resource / constraint / field / value).- Line 950, in the rate-limiting section:
// Response: "DUPLICATE_RECORD" or "VALIDATION_ERROR" for a registration attempt.
What the platform does
So the error-handling page describes a wire body no route emits, and the example's details.value echoes the offending value, which the platform sentence deliberately withholds (the driver's error stays on cause).
Not measured here
- Whether the
{ "success": false, "error": { ... } } envelope shape on that page matches today's ADR-0112 body at all — the whole section may predate the current envelope; this card records only the code spelling.
- Whether
content/docs/api/error-catalog.mdx line 355 (### DUPLICATE_RECORD, "A record with the same unique key already exists") needs a note distinguishing the in-process code from the wire spelling; it is a catalog entry, not an HTTP example, so it may be fine as-is.
Suggested disposition
Docs-only: rewrite the DUPLICATE_RECORD entry on error-handling.mdx to say the 409 wire body carries UNIQUE_VIOLATION (cross-reference http-protocol.mdx), keep DUPLICATE_RECORD documented as the engine-envelope code an in-process caller branches on, and drop the value echo from the example. Leave for triage to grade.
Observation recorded while implementing #14723 (maintainer ruling A: a unique-constraint refusal has ONE wire spelling on every route,
UNIQUE_VIOLATION; the engine's thrownDuplicateRecordError.codestaysDUPLICATE_RECORDin-process). Filed unassigned; not addressed by the #14723 PR, whose surface is code, pins and changesets.What the page says
content/docs/protocol/kernel/error-handling.mdx, section## Error Codes/### Resource Errors, at line 349 onorigin/main2ed6be649:#### DUPLICATE_RECORD— "HTTP Status: 409", "Meaning: Resource with unique constraint already exists", with an example HTTP body whoseerror.codeis"DUPLICATE_RECORD"(and adetailsobject carryingresource/constraint/field/value).// Response: "DUPLICATE_RECORD" or "VALIDATION_ERROR"for a registration attempt.What the platform does
content/docs/protocol/kernel/http-protocol.mdxlines 759 and 775 document the 409 constraint-violation body as"code": "UNIQUE_VIOLATION"— the spelling the ruling on rest/metadata-protocol: one unique conflict, two wire spellings on ONE route — a batch/import ROW reportsDUPLICATE_RECORDwhile the whole-request failure on the same route reportsUNIQUE_VIOLATION#14723 names as the published one.UNIQUE_VIOLATION: the single-record door (唯一约束冲突没有单一判别谓词:仓内四套各自为政的方言词表,REST 的 409 映射漏掉 MySQL(Duplicate entry落成 500 INTERNAL_ERROR) #6250 / REST: the UNIQUE_VIOLATION 409 message is hard-coded English and carries no field — and it is less informative than the bulk path's own message for the same constraint #7821 /mapDataErrorhas noDUPLICATE_RECORDarm: the engine's insert conflict envelope reaches the wire through the generic passthrough, dropping thefieldkey and the user-facing conflict sentence #14389), the whole-request bulk / import / metadata / UI doors (Routes exiting throughhandleRouteErroranswer the engine'sDUPLICATE_RECORDenvelope fromresolveErrorResponse's.statuspassthrough —fieldandobjectdropped,mapDataError's structured 409 arms never consulted #14541), and after rest/metadata-protocol: one unique conflict, two wire spellings on ONE route — a batch/import ROW reportsDUPLICATE_RECORDwhile the whole-request failure on the same route reportsUNIQUE_VIOLATION#14723 the per-row reports ofPOST /api/v1/data/:object/batchand the import runner.DUPLICATE_RECORDis the engine's in-process identity (a hook or a flow node catchingDuplicateRecordErrorsees it —content/docs/automation/flows.mdxline 1124 documents that correctly), never an HTTP body'scode.So the error-handling page describes a wire body no route emits, and the example's
details.valueechoes the offending value, which the platform sentence deliberately withholds (the driver's error stays oncause).Not measured here
{ "success": false, "error": { ... } }envelope shape on that page matches today's ADR-0112 body at all — the whole section may predate the current envelope; this card records only the code spelling.content/docs/api/error-catalog.mdxline 355 (### DUPLICATE_RECORD, "A record with the same unique key already exists") needs a note distinguishing the in-process code from the wire spelling; it is a catalog entry, not an HTTP example, so it may be fine as-is.Suggested disposition
Docs-only: rewrite the
DUPLICATE_RECORDentry onerror-handling.mdxto say the 409 wire body carriesUNIQUE_VIOLATION(cross-referencehttp-protocol.mdx), keepDUPLICATE_RECORDdocumented as the engine-envelope code an in-process caller branches on, and drop the value echo from the example. Leave for triage to grade.