How-to › Make calls that survive failure

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.

Audience
Library maintainer
Level
advanced
Topic
Handle and design API errors
Languages
TypeScript, Python and Go
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Kiota error mappingsYou want a class per declared error schema, generated, in each language Kiota supportsPath-shaped request builders, a runtime package per language, and class names taken from your schema namesCallers want entity methods, or a language Kiota does not generate
ogen interface responsesA Go client whose callers switch on a result type instead of matching an errorGo only, a declared failure arrives beside a nil error, and its runtime requires Go 1.26Callers expect errors.As, or you ship more languages than Go
OpenAPI Generator ApiExceptionThe Python or Go client, where the declared model arrives on the exceptionBehavior that differs by generator: typescript-fetch throws one ResponseError holding the raw responseEvery target must behave alike without template work
openapi-typescript and openapi-fetchTypeScript only, and a typed value beside the response is enoughNo class and nothing thrown: error is returned, and is a union when one operation declares several schemasCallers catch by class, or you ship more than TypeScript
sdkgen project featuresdkgen generates the SDK and you want the same classes in every targetA mapping you write and maintain per target, because the model reads success schemas onlyYou 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.

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

  1. 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

  2. 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

  3. Kiota’s error handling page 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.