Document namespaced-errors OpenAPI setting

[devin-ai-integration]

Summary

settings.namespaced-errors is a new opt-in, per-spec OpenAPI setting in generators.yml (Fern CLI 5.114.0/5.114.1). By default Fern compares shared error responses across the whole API by status code, so when two specs return different bodies for the same status (e.g. two different 429 bodies) the shared error's body collapses to unknown/any in generated SDKs. With the setting enabled, a response object in components.responses tagged x-fern-sdk-namespace: <name> is declared in that namespace and conflict-checked only within it, so customers get typed per-namespace error classes (e.g. plants.TooManyRequestsError) while keeping the spec's endpoints and other types at the root. Only the response-object extension is honored, and the setting applies only to the spec that sets it.

The x-fern-sdk-namespace extension itself (CLI 0.58.0+) was never documented, so this PR also adds a proper extension page rather than describing the extension only in terms of the new setting.

Implements docs for: feat(openapi): add namespaced-errors setting to scope errors by response/body-schema namespace (fern-api/fern#17650) — fern-api/fern#17650 and fix(openapi): scope namespaced-errors to its spec and only honor response-object namespace (fern-api/fern#17655) — fern-api/fern#17655

Pages changed:

• fern/products/api-def/openapi/extensions/sdk-namespace.mdx (new, /learn/api-definitions/openapi/extensions/sdk-namespaces) — documents x-fern-sdk-namespace on components.schemas (per-schema namespace override, verified against generateIr.ts/AbstractOpenAPIV3ParserContext.ts) and on components.responses (shared errors, gated by namespaced-errors, verified against convertResponse.ts). Registered in api-def.yml next to SDK variables.
• fern/snippets/openapi-specs.mdx — new settings.namespaced-errors ParamField linking to the extension page (rendered on both the SDKs generators.yml reference and the API definitions generators.yml reference).
• fern/products/api-def/openapi/extensions/overview.md — x-fern-sdk-namespace row in the extensions table linking to the new page.
• fern/products/api-def/pages/project-structure.mdx — one-sentence pointer from the "Add namespaces" step.

No global api.settings entry was added: that section only documents auto-generate-idempotency-key and defers per-type settings to the spec-type snippets. pre-commit (Vale) and fern check --warnings pass.

Link to Devin session: https://app.devin.ai/sessions/ee10ef9037304e51a72dec484d7bd7d1
Open in Devin Desktop: https://app.devin.ai/desktop/session/ee10ef9037304e51a72dec484d7bd7d1?variant=devin

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1788714403-namespaced-errors-setting.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/api-definitions/openapi/extensions/sdk-namespaces
• learn/api-definitions/overview/project-structure