fix(api): give the shared write ceiling a code a client can branch on

The eleven single-record writes answered their shared 429 with prose and
nothing else, while the envelope's own description tells a client to
branch on `meta.errorCode`. On `POST /api/medications/[id]/intake` and
`POST /api/cycle/day-logs` a second, narrower bucket can answer 429 as
well, so the presence of the rate-limit headers was the only thing
telling the two refusals apart.

All eleven now carry `record_write.rate_limited`, the catalogue lists
it, the published 429 names it, and the contract test fails if a site
stops emitting it or the sentence stops publishing it.

The same description now states what a client could not predict from
"300 requests per 60 seconds": refused requests count too, because the
check runs before the body is read.

docs/api/openapi.yaml

@@ -392,12 +392,15 @@ paths:
         "409": *a7
         "422": *a4
         "429": &a10
-          description: Rate limit exceeded. This route shares one per-account bucket with the other single-record writes —
+          description: "Rate limit exceeded. This route shares one per-account bucket with the other single-record writes —
             `record-write:<accountId>`, 300 requests per 60 seconds — keyed on the ACTING account, so a delegate burns
-            their own allowance rather than the record owner's. Nothing was written. The `Retry-After`,
-            `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describe that bucket; back off
-            on `Retry-After` rather than guessing. A client with more than a handful of rows to send should use the
-            batch endpoint for its domain instead of looping this one.
+            their own allowance rather than the record owner's. Nothing was written. `meta.errorCode` is
+            `record_write.rate_limited`, which is what tells this refusal apart from a route's own narrower bucket when
+            both can answer 429. The `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`
+            headers describe that bucket; back off on `Retry-After` rather than guessing. Every request counts against
+            the bucket, refused ones included: the check runs before the body is read, so a client looping on a 422
+            spends the same allowance as one that writes rows. A client with more than a handful of rows to send should
+            use the batch endpoint for its domain instead of looping this one."
           headers: *a8
           content:
             application/json:
@@ -29574,21 +29577,21 @@ components:
                 onboarding.step.concurrent, onboarding.step.invalid, onboarding.step.outOfOrder,
                 onboarding.step.rateLimited, onboarding.tour.invalid, onboarding.user.notFound; personal_records —
                 personal_records.invalid_query; practitioner — practitioner.invalid; profile —
-                profile.update.emailInUse, profile.update.invalidBody, profile.update.nothingSaved; report-selection —
-                report-selection.body.invalid_json, report-selection.body.invalid_shape,
-                report-selection.leaves.unknown; route — route.retired; share-link — share-link.document.decryptFailed,
-                share-link.document.notFound, share-link.document.rateLimited, share-link.documents.invalid,
-                share-link.report.notFound, share-link.report.rateLimited, share-link.selection.forbidden_leaf,
-                share-link.selection.unknown_leaf; sharing — sharing.accept.expired, sharing.accept.not_found,
-                sharing.accept.not_pending, sharing.accept.revoked, sharing.access.denied, sharing.invite.duplicate,
-                sharing.invite.invalid, sharing.invite.invalid_scope, sharing.invite.manage_browser_only,
-                sharing.invite.refused, sharing.invite.self, sharing.not_permitted, sharing.renounce.already_ended,
-                sharing.renounce.not_found, sharing.revoke.already_ended, sharing.revoke.not_found,
-                sharing.session.changed, sharing.switch.invalid, sharing.switch.wrong_transport; source-priority —
-                source-priority.body.invalid_json, source-priority.body.invalid_shape; tokens —
-                tokens.measurements.ceiling_reached; vaccination — vaccination.booster-invalid,
-                vaccination.booster-no-antigen, vaccination.encounter-not-found, vaccination.identity-required,
-                vaccination.invalid, vaccination.link.invalid, vaccination.not-found,
+                profile.update.emailInUse, profile.update.invalidBody, profile.update.nothingSaved; record_write —
+                record_write.rate_limited; report-selection — report-selection.body.invalid_json,
+                report-selection.body.invalid_shape, report-selection.leaves.unknown; route — route.retired; share-link
+                — share-link.document.decryptFailed, share-link.document.notFound, share-link.document.rateLimited,
+                share-link.documents.invalid, share-link.report.notFound, share-link.report.rateLimited,
+                share-link.selection.forbidden_leaf, share-link.selection.unknown_leaf; sharing —
+                sharing.accept.expired, sharing.accept.not_found, sharing.accept.not_pending, sharing.accept.revoked,
+                sharing.access.denied, sharing.invite.duplicate, sharing.invite.invalid, sharing.invite.invalid_scope,
+                sharing.invite.manage_browser_only, sharing.invite.refused, sharing.invite.self, sharing.not_permitted,
+                sharing.renounce.already_ended, sharing.renounce.not_found, sharing.revoke.already_ended,
+                sharing.revoke.not_found, sharing.session.changed, sharing.switch.invalid,
+                sharing.switch.wrong_transport; source-priority — source-priority.body.invalid_json,
+                source-priority.body.invalid_shape; tokens — tokens.measurements.ceiling_reached; vaccination —
+                vaccination.booster-invalid, vaccination.booster-no-antigen, vaccination.encounter-not-found,
+                vaccination.identity-required, vaccination.invalid, vaccination.link.invalid, vaccination.not-found,
                 vaccination.practitioner-not-found; workout — workout.batch.invalid, workout.batch.payload_too_large,
                 workout.batch.too_large; (unprefixed) — about_me_conflict, ai_response_truncated, coach_prefs_conflict,
                 dashboard_layout_conflict, empty_file, health_score_config_conflict, insights_layout_conflict,

src/__tests__/record-write-rate-limit-contract.test.ts

@@ -128,6 +128,18 @@ describe("the shared single-record write bucket", () => {
     expect(missing).toEqual([]);
   });
 
+  it("names the code it publishes at every site", () => {
+    // The prose is not the discriminator: two of these routes consult a second
+    // bucket of their own, and a client that can only read `error` cannot tell
+    // which one refused it.
+    const silent = ON_THE_SHARED_BUCKET.filter(([route]) => {
+      const src = readFileSync(join(process.cwd(), route), "utf8");
+      return !src.includes('errorCode: "record_write.rate_limited"');
+    }).map(([route]) => route);
+    expect(silent).toEqual([]);
+    expect(published).toContain("record_write.rate_limited");
+  });
+
   it("is published on every operation that answers it", () => {
     const doc = buildOpenApiDocument() as {
       paths: Record<

src/app/api/allergies/route.ts

@@ -93,7 +93,9 @@ async function postAllergy(request: NextRequest): Promise<Response> {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: rawBody, error: jsonError } = await safeJson(request, {

src/app/api/biomarkers/route.ts

@@ -103,7 +103,9 @@ async function postBiomarker(request: NextRequest) {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: body, error: jsonError } = await safeJson(request, {

src/app/api/custom-metrics/[id]/entries/route.ts

@@ -112,7 +112,9 @@ async function postCustomMetricEntry(
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(user.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
   const { id } = await params;
 

src/app/api/cycle/day-logs/route.ts

@@ -105,7 +105,9 @@ async function postDayLog(request: NextRequest): Promise<Response> {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: rawBody, error: jsonError } = await safeJson(request, {

src/app/api/encounters/route.ts

@@ -162,7 +162,9 @@ async function postEncounter(request: NextRequest): Promise<Response> {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: rawBody, error: jsonError } = await safeJson(request, {

src/app/api/labs/route.ts

@@ -156,7 +156,9 @@ async function postLabResult(request: NextRequest) {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: body, error: jsonError } = await safeJson(request, {

src/app/api/measurements/route.ts

@@ -807,7 +807,9 @@ async function postMeasurement(request: NextRequest) {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(auth.actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: body, error: jsonError } = await safeJson(request, {

src/app/api/medications/[id]/intake/route.ts

@@ -64,7 +64,9 @@ async function postIntake(request: NextRequest, { params }: RouteParams) {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   // v1.36.1 follow-up — the sibling route `POST /api/medications/intake`

src/app/api/medications/intake/route.ts

@@ -209,7 +209,9 @@ export const POST = apiHandler(async (request: NextRequest) => {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: body, error } = await safeJson(request, {

src/app/api/mood-entries/route.ts

@@ -111,7 +111,9 @@ async function postMoodEntry(request: NextRequest) {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: body, error: jsonError } = await safeJson(request, {

src/app/api/vaccinations/route.ts

@@ -120,7 +120,9 @@ async function postVaccination(request: NextRequest): Promise<Response> {
   // client hits were not.
   const writeRl = await checkRecordWriteRateLimit(actor.id);
   if (!writeRl.allowed) {
-    return apiError("Too many writes, try again later", 429);
+    return apiError("Too many writes, try again later", 429, {
+      errorCode: "record_write.rate_limited",
+    });
   }
 
   const { data: rawBody, error: jsonError } = await safeJson(request, {

src/lib/openapi/error-codes.ts

@@ -251,6 +251,7 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
       "profile.update.invalidBody",
       "profile.update.nothingSaved",
     ],
+    record_write: ["record_write.rate_limited"],
     "report-selection": [
       "report-selection.body.invalid_json",
       "report-selection.body.invalid_shape",

src/lib/openapi/routes/shared.ts

@@ -312,7 +312,7 @@ export const stdResponses = {
 export const recordWriteRateLimitResponse = {
   "429": {
     description:
-      "Rate limit exceeded. This route shares one per-account bucket with the other single-record writes — `record-write:<accountId>`, 300 requests per 60 seconds — keyed on the ACTING account, so a delegate burns their own allowance rather than the record owner's. Nothing was written. The `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describe that bucket; back off on `Retry-After` rather than guessing. A client with more than a handful of rows to send should use the batch endpoint for its domain instead of looping this one.",
+      "Rate limit exceeded. This route shares one per-account bucket with the other single-record writes — `record-write:<accountId>`, 300 requests per 60 seconds — keyed on the ACTING account, so a delegate burns their own allowance rather than the record owner's. Nothing was written. `meta.errorCode` is `record_write.rate_limited`, which is what tells this refusal apart from a route's own narrower bucket when both can answer 429. The `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describe that bucket; back off on `Retry-After` rather than guessing. Every request counts against the bucket, refused ones included: the check runs before the body is read, so a client looping on a 422 spends the same allowance as one that writes rows. A client with more than a handful of rows to send should use the batch endpoint for its domain instead of looping this one.",
     content: { "application/json": { schema: errorEnvelope } },
     headers: stdResponses["429"].headers,
   },