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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| hand-written fetch | One or two calls, and you want to see every header you send | Each media type encoded by hand, and a multipart header you must leave to fetch | The API has many operations, or clients in several languages |
Kiota --structured-mime-types | You generate with Kiota and the API prefers a type other than JSON | One weighting for the whole document, so two operations cannot differ | One operation takes a form and another takes JSON |
| OpenAPI Generator | Its typescript-fetch client, which sends the first media type the document lists | A rule that differs by generator: the Python client prefers JSON, with _content_type per call | You cannot reorder the document, or need one rule everywhere |
| openapi-typescript and openapi-fetch | TypeScript, and each call site can name its own media type | JSON unless the call sets a header or a bodySerializer, repeated at every call site | The document should decide, not each caller |
sdkgen guide body.media | sdkgen generates the SDK and its model picked the wrong type from several | A corrected model that the generated runtime honors for JSON and raw bodies only | The API takes a form or multipart, which needs a hook besides |
| Swagger Codegen templates | You generate with Swagger Codegen and can change the document it reads | No media type option, so the fix is the document or a template folder you maintain | The 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.
Related how-tos
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
-
RFC 9110 spends two sentences on what a 415 should carry. For an unsupported content coding, the
Accept-Encodingresponse header “ought to be used,” in its words. For an unsupported media type, theAcceptresponse header “can be used,” and no more than that. The media type got the weaker verb. ↩︎ Back to text -
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
-
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