How-to › Operate integrations in production

How to debug why a generated SDK sends the wrong content type#

Capture the Content-Type a generated SDK sends, trace it to the OpenAPI document and the generator's choice, and fix it where regeneration keeps the fix.

Audience
API producer
Level
intermediate
Topic
Debug an integration
Languages
TypeScript and Python
Verified

Your generated SDK’s create call comes back 415 Unsupported Media Type. The API takes a URL-encoded form, the OpenAPI document lists JSON beside it, and the generator picked JSON. The request is built inside generated code, so the header that went out is a guess until you capture it.

What you get

You will end up with the Content-Type your SDK sends, the document entry behind it, the choice your generator made, and a fix that survives regeneration. This is for you if you ship a generated SDK whose calls fail with 415 or 400.

Short answer

To debug a wrong Content-Type from an sdkgen SDK, capture the header with mitmproxy in reverse mode or the SDK’s own explain record, then read the rb entry of the operation in .sdk/model/entity. It shows the media type the model chose from requestBody.content. Correct it with body.media in the guide file, regenerate, and capture again. In the version run here, a form body also needs a hook to encode it.

You will need

Node 22 or later, an OpenAPI 3 document, and a generated SDK whose calls fail with 415 or 400. The capture step uses mitmproxy. Verified 2026-11-19 against @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Swagger Codegen 3.0.85, openapi-typescript 7.13.0, openapi-fetch 0.17.0, and mitmproxy 12.3.1. The API here is a stand-in on the loopback interface. Its POST /books takes a form and answers 415 to JSON, though api.json lists both, and it records the Content-Type of every request.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
hand-written fetchOne or two calls, and you want to see every header you sendEach media type encoded by hand, and a multipart header you must leave to fetchThe API has many operations, or clients in several languages
Kiota --structured-mime-typesYou generate with Kiota and the API prefers a type other than JSONOne weighting for the whole document, so two operations cannot differOne operation takes a form and another takes JSON
OpenAPI GeneratorIts typescript-fetch client, which sends the first media type the document listsA rule that differs by generator: the Python client prefers JSON, with _content_type per callYou cannot reorder the document, or need one rule everywhere
openapi-typescript and openapi-fetchTypeScript, and each call site can name its own media typeJSON unless the call sets a header or a bodySerializer, repeated at every call siteThe document should decide, not each caller
sdkgen guide body.mediasdkgen generates the SDK and its model picked the wrong type from severalA corrected model that the generated runtime honors for JSON and raw bodies onlyThe API takes a form or multipart, which needs a hook besides
Swagger Codegen templatesYou generate with Swagger Codegen and can change the document it readsNo media type option, so the fix is the document or a template folder you maintainThe operation is multipart and the client is typescript-fetch

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

Three layers can carry the fix. The document reaches every generator that reads it, but Swagger Codegen and OpenAPI Generator read the same list differently. A generator override, Kiota’s weights or sdkgen’s guide, leaves a document you may not own alone, and binds the fix to one tool. A patch to generated code lasts until the next regeneration.

Capture the header that went out

A reverse proxy needs no proxy setting and no certificate in the client. Start mitmproxy in front of the API with a script that prints one line per request, and point the SDK’s base URL at the proxy.

def request(flow):
    sent = flow.request.headers.get("content-type", "(none)")
    print(flow.request.method, flow.request.path, "content-type:", sent, flush=True)
mitmdump -q -s capture.py --mode reverse:API_ORIGIN -p 8080

Run by hand in front of the stand-in, with the SDK as first generated and its base set to http://127.0.0.1:8080/v1, the script printed POST /v1/books content-type: application/json. The 415 agrees with it. RFC 9110 lets a server name the types it would have accepted in an Accept response header, and the stand-in sends application/x-www-form-urlencoded there.1

Trace the choice to the document and the model

The header comes from the operation’s requestBody.content, a map with one key for each media type the API says it takes.

"requestBody": { "required": true, "content": {
  "application/json": {
    "schema": { "$ref": "#/components/schemas/NewBook" } },
  "application/x-www-form-urlencoded": {
    "schema": { "$ref": "#/components/schemas/NewBook" } }
} },

A client sends one of them, so every generator has a rule for choosing. OpenAPI Generator’s TypeScript client sends the first key listed,2 Kiota weighs the types, and sdkgen prefers JSON whenever the document offers it. sdkgen also writes its choice down, as the rb entry of the operation in the entity model. model.mjs reads that entry from the model as first generated, and again after the correction that follows.

node model.mjs
model-before/book.aontu
  create sends  application/json (kind json)
  alternatives  application/x-www-form-urlencoded
model-after/book.aontu
  create sends  application/x-www-form-urlencoded (kind form)
  alternatives  application/json

The correction is one line in .sdk/model/guide/guide.aontu, which generation reads and leaves as you wrote it. The model reference gives the rule it overrides.

guide: entity: book: path: "/books": op: create: body: media: "application/x-www-form-urlencoded"

Capture again after you regenerate

Regenerate, then capture again, this time without a proxy. An sdkgen SDK records the request it built when the call’s control argument carries an explain object.

// The explain record is the SDK's own account of the request it built.
const ctrl = { explain: {} }
// A 415 rejects; the record and the stand-in's log say what happened.
await sdk.Book().create(BOOK, ctrl).catch(() => {})
const { headers, body } = ctrl.explain.fetchdef
node demo.mjs
book.create, model corrected
  the SDK built     content-type: application/json
                    body: {"author":"Jane Austen","published":1817,"title":"Persuasion"}
  the API received  content-type: application/json
  the API answered  415

The model changed, but the request did not. In the version run here, the generated runtime sets the header for json and raw bodies only, in the TypeScript and Python targets alike, so a form body still goes out as JSON. The corrected entry does reach the SDK, as ctx.point.body, and a hook can act on it. generate.sh adds this one as a feature of the project’s own, under .sdk:

// The request spec is built and not yet sent.
PreRequest(this: any, ctx: any) {
  const declared = ctx.point?.body
  const data = ctx.spec?.body
  if ('form' !== declared?.kind || null == data || 'object' !== typeof data) {
    return
  }

  const form = new URLSearchParams()
  for (const field of declared.fields ?? []) {
    if (Object.hasOwn(data, field.name) && null != data[field.name]) {
      form.append(field.name, String(data[field.name]))
    }
  }

  const headers = ctx.spec.headers
  for (const name of Object.keys(headers)) {
    if ('content-type' === name.toLowerCase()) {
      delete headers[name]
    }
  }
  headers['content-type'] = declared.media
  ctx.spec.body = form.toString()
}

With feature: { formbody: { active: true } } in the constructor, the same call goes through:

node demo.mjs
book.create, model corrected, formbody feature on
  the SDK built     content-type: application/x-www-form-urlencoded
                    body: author=Jane+Austen&published=1817&title=Persuasion
  the API received  content-type: application/x-www-form-urlencoded
  the API answered  201

Fix the document for Swagger Codegen

Swagger Codegen has no option that selects a media type: config-help lists none for its typescript-fetch or python generator. With both types listed, its TypeScript client assigns the header twice, and the JSON assignment comes last.

localVarHeaderParameter['Content-Type'] = 'application/x-www-form-urlencoded';

localVarHeaderParameter['Content-Type'] = 'application/json';

swagger-demo.mjs calls that client, then the one generated from api-form.json, which is api.json with the JSON entry removed.

node swagger-demo.mjs
generated from api.json
  createBook   sent content-type: application/json                   answered 415
  uploadCover  sent content-type: application/x-www-form-urlencoded  answered 415
generated from api-form.json
  createBook   sent content-type: application/x-www-form-urlencoded  answered 201

Removing the entry fixes createBook. Reordering the entries does not: a run outside the sample changed the header and left the body as JSON. uploadCover is the reverse failure, a multipart/form-data operation sent URL-encoded, though the document lists that type alone. The documented lever there is a template folder passed with -t. The Python client declares the multipart type for that operation, and picks among several types with this rule:

if 'application/json' in content_types or '*/*' in content_types:
    return 'application/json'
else:
    return content_types[0]

Name the media type per call in openapi-fetch

openapi-typescript writes both media types into the type of body, and openapi-fetch reads no document at run time. It serializes and labels every body as JSON unless the call says otherwise. Its documentation gives two switches: a Content-Type header of application/x-www-form-urlencoded, which makes the default serializer URL-encode the body, and a bodySerializer that returns a FormData.

node fetch-demo.mjs
POST /books, body alone   sent content-type: application/json                   answered 415
POST /books, form header  sent content-type: application/x-www-form-urlencoded  answered 201
POST cover, FormData      sent content-type: multipart/form-data; boundary=...  answered 201

The fix lives at each call site, so two callers of one operation can disagree.

Check it worked

Ten tests pin every row of those outputs against the stand-in.

node --test content-type.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0

# pass 10 includes the test that expects the body author=Jane+Austen&published=1817&title=Persuasion and a 201 with the feature on. Remove the feature’s PreRequest method and that test fails on application/json.

When it goes wrong

A multipart upload answers 400 after you set the header yourself. A Content-Type of multipart/form-data written by hand replaces the one fetch would write, and the boundary parameter goes with it. RFC 7578 makes that parameter required,3 so the server cannot find the parts. Leave the header unset.

node pitfall.mjs
Content-Type left to fetch  sent content-type: multipart/form-data; boundary=...  answered 201
Content-Type set by hand    sent content-type: multipart/form-data                answered 400

The fix disappears after a release. It was an edit to a generated file, and the next regeneration overwrote it. Move it to the document, the generator’s override, or a hook the generator keeps.

The SDK’s record and the capture disagree. A record made inside the SDK shows the request it handed to fetch. A header that fetch completes, such as the multipart boundary, shows only on the wire.

When not to do this

Do not patch the generated request code, in any generator. The patch works once and teaches nobody where the choice was made.

Do not stop at sdkgen’s guide when the API takes a form. As run here, the correction changes the model and not the request, and the hook is code you maintain for every target you ship. Swagger Codegen is the better choice when you can correct the document and the body is a URL-encoded form. Remove one entry, and its client sends the form with no code from you. openapi-fetch is the better choice when callers must choose per call, or the body is multipart, where a FormData serializer is the whole fix.

Do not correct the client when the server is the one at fault. If the document says the API takes JSON, and you own the API, accepting JSON repairs every SDK already published.

Do not trust a green regeneration. Capture the header again.

Last verified

Verified 2026-11-19 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Swagger Codegen 3.0.85, openapi-typescript 7.13.0, and openapi-fetch 0.17.0. Every output block is what the command preceding it printed. The generation runs are not repeated by those commands: their output is committed, and generate.sh records them. mitmproxy 12.3.1 was run by hand with capture.py, and its line is quoted in the text. The Python target, the reordered document, and the Kiota 1.38.0 and OpenAPI Generator 7.27.0 runs behind their table rows were run outside the sample.

Footnotes

  1. RFC 9110 spends two sentences on what a 415 should carry. For an unsupported content coding, the Accept-Encoding response header “ought to be used,” in its words. For an unsupported media type, the Accept response header “can be used,” and no more than that. The media type got the weaker verb. ↩︎ Back to text

  2. The first key listed is a property of the file more than of the document. RFC 8259 defines a JSON object as an unordered collection of name and value pairs, and observes that parsing libraries differ on whether they show member order to the software calling them. A generator that follows the order is reading something the format declines to promise. ↩︎ Back to text

  3. RFC 7578 replaced RFC 2388 in July 2015, and its list of changes says that “boundary” became a required parameter of the Content-Type. The parts of the body are delimited by a line break, two hyphens, and that value, so a header without it describes a body nobody can cut up. ↩︎ 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.