feat: cross-link shared device errors from sub-category error pages

[dawnho]

Summary

Follow-up improvements to the API-reference errors-page generator (mintlify-codegen/errors.ts), building on #1219 and #1209.

Device sub-categories (locks, thermostats, phones) are not distinct blueprint resources — the Seam API models them as devices, so their error/warning codes live on the device resource under variant groups. #1219 added the DEVICE_SUBCATEGORY_ERROR_ROUTES allowlist + variantGroupProp() to emit dedicated pages for those. Their pages are subsets of the aggregate /api/devices/errors page.

1. Cross-link the shared device errors from the lock/thermostat pages (primary)

The sub-category pages omit the device-level codes (device_offline, device_disconnected, missing_device_credentials, …) that live on /api/devices/errors. A reader troubleshooting connectivity on /api/locks/errors couldn't find device_offline there.

The lock and thermostat pages now open with a <Note> linking back to the shared page:

These are Lock-specific errors and warnings. For errors and warnings common to all devices, see Device Errors and Warnings.

The note is derived from the page's noun (resourceNoun()) and its actual sections. The link target /api/devices/errors is registered in docs.json and matches the form other pages already use. The note is added only on sub-category pages, never on /api/devices/errors itself.

The phones page deliberately omits the note. The shared codes are physical-device connectivity/subscription errors (device_offline, hub_disconnected, salto_ks_subscription_limit_exceeded, …) that apply to locks and thermostats but not to phones (mobile devices used for credentials), so pointing a phones reader at them would be misleading. This is encoded per sub-category: DEVICE_SUBCATEGORY_ERROR_ROUTES now carries a linkCommonDeviceErrors flag (true for locks/thermostats, false for phones) alongside each route.

Implemented via a commonDeviceErrorsRoute option threaded through writeErrorPage(), set at the device-sub-category call site only when the sub-category shares the device-level codes.

2. Make the allowlist self-checking (secondary)

DEVICE_SUBCATEGORY_ERROR_ROUTES is hand-maintained, so a new device sub-category with its own docs route (object + events pages) and an error/warning variant group would silently produce no errors page until someone edited the map.

The generator now logs a warning when a device errors/warnings variant group key: (a) has non-empty codes, (b) has both /api/<key>/object.mdx and /api/<key>/events.mdx, and (c) is not in the allowlist and is not itself a documented blueprint resource. Condition (c) is what prevents false positives on real resources (access_codes, which owns its own distinct errors) and annotation-only groups (hardware, provider_metadata, which have no such route). The current blueprint produces zero warnings; verified the warning fires correctly when locks is temporarily removed from the allowlist.

3. Defensive double-write guard (reduce drift)

Added a guard in writeErrorPage() to skip a routePath already written. This surfaced a latent collision: device_provider is a documented resource that shares routePath /devices with device. Previously the second write was avoided only implicitly (via device_provider's empty-codes early-return); the guard makes the ordering explicit and prevents a future clobber. Verified /api/devices/errors output is byte-identical to main.

Relationship to #1210

Docs PR #1210 currently links lock/thermostat troubleshooting to /api/devices/errors (rather than the sub-category resource pages) precisely because the sub-category pages lacked the device-level codes. Improvement #1 is the prerequisite that would later let those links point at the sub-category resource pages while still directing readers to the shared device-level codes.

Verification

• npm run generate:mintlify — the lock and thermostat pages gained the cross-link note, the phones page did not; no new warnings fire.
• npm run typecheck, npm run lint, npm run format all pass.
• openapi.json code-sample reformatting churn (from missing ruff/shfmt/stree in this environment) was not committed — only the generator + the 3 regenerated errors.mdx pages are included.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
seam	🟢 Ready	View Preview	Jul 2, 2026, 8:17 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.