# How to expose typed error classes from a generated SDK

> Give a generated SDK one error class per declared error response, with the problem document parsed into fields, and catch each class in TypeScript, Python, and Go.

Source: https://voxgig.com/howto/typed-error-classes-in-a-generated-sdk

- Audience: library-maintainer
- Level: advanced
- Languages: typescript, python, go
- Verified: 2026-11-19
- Published: 2026-11-19

## Short answer

To expose typed error classes from an sdkgen SDK, add a feature of your own under .sdk whose PreUnexpected hook throws one class per declared error response, with one source file for each target. As generated, the SDK raises a single error class that carries the status and the parsed problem document. Kiota and openapi-typescript read the error schemas from the document with no code from you, so compare them first.

---
## You will need

Node 22 or later, Python 3.13 with `requests`, Go 1.24 or later, and an OpenAPI 3 document that
declares a schema for each error status. Verified 2026-11-19 against `@voxgig/create-sdkgen`
0.31.9, `@voxgig/sdkgen` 4.44.3, `openapi-typescript` 7.13.0, `openapi-fetch` 0.17.0, and `ogen`
1.25.0. The document here, `api.json`, is a Bookshelf API whose error bodies are
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem details.[^1] Every demo talks to a
stand-in on the loopback interface. On Node 22 the scaffold's install prints `EBADENGINE`
warnings, and generation still completes.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Kiota error mappings](https://learn.microsoft.com/en-us/openapi/kiota/errors) | You want a class per declared error schema, generated, in each language Kiota supports | Path-shaped request builders, a runtime package per language, and class names taken from your schema names | Callers want entity methods, or a language Kiota does not generate |
| [`ogen` interface responses](https://ogen.dev/docs/concepts/interface_responses/) | A Go client whose callers switch on a result type instead of matching an error | Go only, a declared failure arrives beside a nil `error`, and its runtime requires Go 1.26 | Callers expect `errors.As`, or you ship more languages than Go |
| [OpenAPI Generator `ApiException`](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/python/exceptions.mustache) | The Python or Go client, where the declared model arrives on the exception | Behavior that differs by generator: `typescript-fetch` throws one `ResponseError` holding the raw response | Every target must behave alike without template work |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/openapi-fetch/) | TypeScript only, and a typed value beside the response is enough | No class and nothing thrown: `error` is returned, and is a union when one operation declares several schemas | Callers catch by class, or you ship more than TypeScript |
| [sdkgen project feature](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-feature.md) | sdkgen generates the SDK and you want the same classes in every target | A mapping you write and maintain per target, because the model reads success schemas only | You want the document, not your code, to define the classes |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

The split is who reads the error schemas. Kiota reads them and generates a class for each, and
you take its request builders with them. `openapi-typescript` and `ogen` read them into types, but
callers get a returned value instead of a thrown class. OpenAPI Generator reads them in some
generators and not in others. The model sdkgen builds keeps none of them, so the mapping is a hook
you write, once for every language you ship.

## Declare one schema for each status

Every tool in the table that reads error schemas reads them per status, so the document decides
how many classes can exist. Give each status that callers must tell apart its own response entry
and its own schema.

```json title="api.json"
"404": { "description": "No book has this id",
  "content": { "application/problem+json": {
    "schema": { "$ref": "#/components/schemas/NotFoundProblem" } } } }
```

Here the 404 adds the missing `bookId` to the standard members. The 422 adds an `errors` list of
`pointer` and `detail` pairs, the shape RFC 9457 uses for its own
[validation example](https://www.rfc-editor.org/rfc/rfc9457.html#section-3).[^2]

## Read what the generated SDK throws

Scaffold and generate as `generate.sh` in the sample records, then call the SDK against an API
that fails. `demo.mjs` loads a book that does not exist and creates one with an empty title.

```bash
node demo.mjs
```

```text output
problem feature off
  load b404  BookshelfError    status 404  code request_status
             result.body.title "No such book", result.body.bookId "b404"
  create     BookshelfError    status 422  code request_status
             result.body.errors [{"pointer":"/title","detail":"must not be empty"}]
```

Both failures are a `BookshelfError` with the code `request_status`. The status is on the error,
and the problem document is already parsed, but it sits under `result.body` as untyped data.
Neither schema reached the SDK: the model sdkgen builds records the media types of success
responses only. Python raises the same class, and Go returns it as an `error`.

## Add the classes as a feature of the project

sdkgen's extension point is a feature: a class whose methods the operation pipeline calls at
named stages. `PreUnexpected` runs once an operation has failed and the SDK has built its error.
In the version run here, an error thrown from that hook replaces the SDK's own in all three
targets. The
[customization guide](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/customize-and-propagate-templates.md)
puts a feature of the project's own under `.sdk`: a model file that switches the hook on, and
one source file in each target's feature folder.

```aontu title="feature/problem.aontu"
  config: {
    options: active: false
  }

  hook: {
    PreUnexpected: active: true
  }
```

The TypeScript source holds one `Error` subclass per schema, with fields copied from the document
by hand, and this mapping:

```ts title="feature/ProblemFeature.ts"
// One entry per error response the OpenAPI document declares, keyed by the
// operation the model gave the path and the status.
const DECLARED = new Map<string, typeof ProblemError>([
  ['load 404', NotFoundProblem],
  ['create 422', ValidationProblem],
])


class ProblemFeature extends BaseFeature {
  version = '0.0.1'
  name = 'problem'
  active = true

  // The SDK has built its own error and is about to throw it. An error
  // thrown from this hook is the one the caller catches instead.
  PreUnexpected(this: any, ctx: any) {
    const err = ctx.ctrl.err
    const declared = DECLARED.get(ctx.op.name + ' ' + err?.status)
    const problem = err?.result?.body
    if (null != declared && null != problem && 'object' === typeof problem) {
      throw new declared(problem, err)
    }
  }
}
```

The key is the operation and the status, so a 404 from `load` is a `NotFoundProblem` and a 404
from any other call stays generic. Copy the files into the project, add the feature, and
regenerate:

```bash title="generate.sh"
cp ../../feature/problem.aontu model/feature/problem.aontu
mkdir -p tm/ts/src/feature/problem
cp ../../feature/ProblemFeature.ts tm/ts/src/feature/problem/ProblemFeature.ts
cp ../../feature/problem_feature.py tm/py/pkg/feature/problem_feature.py
cp ../../feature/problem_feature.go tm/go/feature/problem_feature.go
npx voxgig-sdkgen feature add problem
npm run generate
```

Write a source for every target before you generate. sdkgen wires a declared feature into each
one, so a target without the file stops importing or compiling. In the version run here,
`npm run generate` then warns that two of the feature's files differ from their source, and
`doctor` lists them as edited. They are the project's own files, and the output is complete.

## Catch each class in all three targets

A feature stays off until the constructor switches it on, with
`feature: { problem: { active: true } }`. The second half of `demo.mjs` does that.

```bash
node demo.mjs
```

```text output
problem feature on
  load b404  NotFoundProblem   status 404  bookId b404
  create     ValidationProblem status 422  errors /title must not be empty
  list       BookshelfError    status 503  code request_status, a status the document does not declare
```

The third call hits a gateway's 503 with a plain-text body. No entry in `DECLARED` matches it, so
the generated error passes through unchanged. The Python target catches with one `except` clause
per class:

```bash
PYTHONPATH=pydeps:generated/py python3 demo.py
```

```text output
problem feature on
  load b404  except NotFoundProblem    status 404  book_id b404
  create     except ValidationProblem  status 422  errors /title must not be empty
  list       except BookshelfError     status 503  code request_status
```

In Go the hook panics with the typed error. The generated pipeline recovers it, wraps it, and
returns it, so match with [`errors.As`](https://pkg.go.dev/errors#As):

```bash
go run .
```

```text output
problem feature on
  load b404  errors.As *NotFoundProblem    status 404  BookID b404
             returned as *utility.cleanedError, so a type assertion matches: false
  create     errors.As *ValidationProblem  status 422  Errors /title must not be empty
  list       errors.As *BookshelfError     status 503  code request_status
```

## Get typed errors from `openapi-fetch` and a Go generator

`openapi-typescript` needs no hook, because it writes every declared response into the types.
This is its output for `getBook`, from the same `api.json`:

```ts title="openapi-typescript/schema.d.ts"
/** @description No book has this id */
404: {
    headers: {
        [name: string]: unknown;
    };
    content: {
        "application/problem+json": components["schemas"]["NotFoundProblem"];
    };
};
```

`openapi-fetch` reads those types, so the `error` a call returns is a `NotFoundProblem` to the
compiler, and `typed.ts` in the sample stops compiling if it is anything else. Its documentation
says every method returns `data`, `error`, and `response`, and treats a 4xx as a response, not a
thrown error. A class to catch is yours to write and to throw from an
[`onResponse` middleware](https://openapi-ts.dev/openapi-fetch/middleware-auth).

```bash
node fetch-demo.mjs
```

```text output
GET  /books/{bookId}  returned error, response.status 404, error.bookId b404
POST /books           returned error, response.status 422, error.errors[0].pointer /title
GET  with middleware  threw NotFoundProblem, bookId b404
```

`ogen` generates Go only, and it needs no hook either. `generate.sh` runs it on the same
`api.json`, and `ogen-inspect.mjs` reads the Go source it wrote.

```bash
node ogen-inspect.mjs
```

```text output
CreateBook returns (CreateBookRes, error)
  CreateBookRes is one of *Book, *ValidationProblem
GetBook returns (GetBookRes, error)
  GetBookRes is one of *Book, *NotFoundProblem
ListBooks returns ([]Book, error)
```

Each declared error schema is a struct, and a variant of its operation's result type. Run by hand
with Go 1.26, `GetBook` for a missing id returned a `*NotFoundProblem` beside a nil `error`. So
callers switch on the result's type, and `error` is left for transport failures and undeclared
statuses. The [convenient errors](https://ogen.dev/docs/concepts/convenient_errors/) mode makes
the opposite trade. When every operation shares one `default` response with a single JSON body,
the generated methods return `(*Book, error)`, and one error type covers every status.

## Check it worked

Eleven tests cover the three targets, the type check, and the pitfalls below.

```bash
node --test errors.test.mjs
```

```text output
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 11` includes a test that asserts `err instanceof NotFoundProblem` with `err.bookId` equal
to `b404`, and two that run the Python and Go demos. Change `'load 404'` in the mapping and the
second test fails.

## When it goes wrong

Every failure arrives as one class. The document declares a single `default` response shared by
every status, so every reader of error schemas has one schema to work with. Generated from
`api-default.json`, the types give both operations the same `error`, and Kiota's documentation
lists the `default` mapping as the last one its runtime tries.[^3] Declare a response per status.

The hook never runs. The generated README passes `extend` an object with a `hooks` map, but the
pipeline in this version calls a method on the feature object.

```bash
node pitfall.mjs
```

```text output
extend: [{ hooks: { PreUnexpected } }]  caught BookshelfError
extend: [{ PreUnexpected }]             caught NotFoundProblem
```

The Go caller's type assertion fails. The pipeline returns the hook's error inside a wrapper, as
the preceding Go output shows. Use `errors.As`.

## When not to do this

Do not write this feature if the document can do the work. With sdkgen the classes exist because
you typed them, once per target. When the document gains a 409 that the mapping lacks, no build
fails, and the 409 arrives as the generic error. The hooks reference lists `PreUnexpected`
without describing an error thrown from it, so the replacement is behavior read from generated
source and pinned here by tests.

Kiota is the better choice when the declared schemas should be the single source, because it
regenerates the classes in every language it supports. `openapi-typescript` with `openapi-fetch`
is the better choice for a TypeScript-only client, where the compiler holds each call site to the
declared schema. `ogen` is the better choice for a Go-only client, because the declared failures
are part of each method's return type and there is no mapping to drift.

Do not add a class for a status callers never branch on. `err.status` and `err.notFound` on the
generated error already answer most questions.

Do not key the mapping on status alone, or a 404 from another operation gets a class whose fields
it cannot fill.

## Related how-tos

- [Expose typed SDK errors callers match without parsing text](/howto/typed-sdk-errors-callers-can-match)

- [Return validation errors a client can map to a form](/howto/field-level-validation-errors-clients-can-map)

- [Verify every error response matches one schema](/howto/verify-every-error-response-matches-one-schema)

- [Evolve an error contract without breaking clients](/howto/evolve-an-error-contract-without-breaking-clients)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

## Last verified

Verified 2026-11-19 against Node 22.23.5, Python 3.13.18, Go 1.24.7, `@voxgig/create-sdkgen`
0.31.9, `@voxgig/sdkgen` 4.44.3, `openapi-typescript` 7.13.0, `openapi-fetch` 0.17.0, TypeScript
5.9.3, and `ogen` 1.25.0. Every output block is what the command preceding it printed. The
scaffold and generate run is not repeated by those commands: its output is committed under
`generated/`, and `generate.sh` records it. The client `ogen` wrote is committed under `ogen/`
and was run by hand with Go 1.26.11, which its runtime requires. The page's commands read its
source without compiling it. The convenient errors variant, and the Kiota 1.38.0 and OpenAPI
Generator 7.27.0 runs behind their table rows, were generated outside the sample.

[^1]: [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) is dated July 2023 and obsoletes
[RFC 7807](https://www.rfc-editor.org/rfc/rfc7807.html) of March 2016, which defined the same
object under the same media type. Its appendix of changes has three entries: a registry of common
problem types, a clarification on multiple problems, and guidance for a type URI that cannot be
dereferenced. Seven years of deployment produced three bullet points.

[^2]: The status has had two names.
[RFC 4918](https://www.rfc-editor.org/rfc/rfc4918.html#section-11.2) defined 422 for WebDAV in
June 2007 as Unprocessable Entity.
[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content) adopted it
for HTTP in June 2022 as Unprocessable Content, and
[Python 3.13](https://docs.python.org/3/library/http.html) renamed its constant to match, keeping
the earlier name for backward compatibility. The number is the part that stayed put.

[^3]: Kiota's [error handling page](https://learn.microsoft.com/en-us/openapi/kiota/errors) gives
the order: a mapping for the exact status code, then one for the range, then one for `default`
responses, then the base exception from its abstractions library. When nothing is mapped, the
caller gets "The server returned an unexpected status code and no error factory is registered for
this code," a sentence the page quotes in full. The first remedy it lists is asking the API
producer to improve the description.