Your OpenAPI document declares a 404 that carries a bookId and a 422 that carries a list of
field errors, but the generated SDK throws one class for both. Callers branch on a status number
and dig the fields out of an untyped body. The schema you wrote for each error never reaches a
caller’s editor.
What you get
You will end up with an SDK that raises NotFoundProblem for the 404 and ValidationProblem for
the 422, each with the problem document parsed into fields, in TypeScript, Python, and Go. This is
for you if you maintain a generated SDK whose callers catch errors.
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 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 | 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 | 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 | 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 | 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 | 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.
"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.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.
node demo.mjs
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
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.
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:
// 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:
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.
node demo.mjs
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:
PYTHONPATH=pydeps:generated/py python3 demo.py
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:
go run .
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:
/** @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.
node fetch-demo.mjs
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.
node ogen-inspect.mjs
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 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.
node --test errors.test.mjs
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.
node pitfall.mjs
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
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.
Footnotes
-
RFC 9457 is dated July 2023 and obsoletes RFC 7807 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. ↩︎ Back to text
-
The status has had two names. RFC 4918 defined 422 for WebDAV in June 2007 as Unprocessable Entity. RFC 9110 adopted it for HTTP in June 2022 as Unprocessable Content, and Python 3.13 renamed its constant to match, keeping the earlier name for backward compatibility. The number is the part that stayed put. ↩︎ Back to text
-
Kiota’s error handling page gives the order: a mapping for the exact status code, then one for the range, then one for
defaultresponses, 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. ↩︎ Back to text