What causes "unsupported status " + resp.code" in OpenAPITools/openapi-generator?

Replace non-standard response codes in the spec with the closest standard status (e.g. 499->400 or 408, 599->500, 299->200)

OpenAPITools/openapi-generator · error · IllegalArgumentException

unsupported status " + resp.code

Error message

unsupported status " + resp.code

What it means

The scala-http4s-server generator maps every response status in an operation to an http4s Status constructor. It looks the code up in ordered maps: Location-style 3xx, WWW-Authenticate 401, Allow 405, Proxy-Authenticate 407, then standard http4s statuses. If the code appears in none of them, generation throws IllegalArgumentException('unsupported status <code>') because there is no http4s Status to emit.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/ScalaHttp4sServerCodegen.java:657

                    resp.vendorExtensions.put("x-response-location", true);
                } else {
                    responseName = wwwAuthStatusToResponse.get(resp.code);
                    if (responseName != null) {
                        resp.vendorExtensions.put("x-response-www-auth", true);
                    } else {
                        responseName = allowStatusToResponse.get(resp.code);
                        if (responseName != null) {
                            resp.vendorExtensions.put("x-response-allow", true);
                        } else {
                            responseName = proxyAuthStatusToResponse.get(resp.code);
                            if (responseName != null) {
                                resp.vendorExtensions.put("x-response-proxy-auth", true);
                            } else {
                                responseName = statusToResponse.get(resp.code);
                                if (responseName != null) {
                                    resp.vendorExtensions.put("x-response-standard", true);
                                } else {
                                    throw new IllegalArgumentException("unsupported status " + resp.code);
                                }
                            }
                        }
                    }
                }

                resp.vendorExtensions.put("x-response", responseName);

                if (resp.getContent() == null) {
                    resp.vendorExtensions.put("x-generic-response", true); // non json resp
                } else {
                    if (resp.getContent().containsKey("application/json")) {
                        resp.vendorExtensions.put("x-json-response", true); // json resp
                    } else {
                        resp.vendorExtensions.put("x-generic-response", true); // non json resp
                    }
                    if (resp.getContent().size() > 1) {
                        resp.vendorExtensions.put("x-generic-response", true); // non json resp

View on GitHub (pinned to fcec517be3)

Solutions

Replace non-standard response codes in the spec with the closest standard status (e.g. 499->400 or 408, 599->500, 299->200)
Keep non-standard codes in documentation/description text instead of as response keys
If the code is IANA-registered but missing from the generator's map, open an issue/PR adding it to statusToResponse in ScalaHttp4sServerCodegen

Example fix

# before
responses:
  '499':
    description: client closed request
# after
responses:
  '408':
    description: client closed request (request timeout)

Defensive patterns

Strategy: validation

Validate before calling

# Lint the spec for status codes http4s cannot represent (Python):
NON_STANDARD = {'299', '499', '598', '599'}  # codes http4s has no Status for; curate as needed
for path, item in spec['paths'].items():
    for method, op in item.items():
        if method in {'get','put','post','delete','options','head','patch','trace'}:
            for code in op.get('responses', {}):
                assert code == 'default' or code not in NON_STANDARD, \
                    f'{method.upper()} {path}: status {code} is unsupported by scala-http4s-server'

Try / catch

try {
    new DefaultGenerator().opts(input).generate();
} catch (IllegalArgumentException e) {
    // 'unsupported status NNN' - replace that response code in the spec with a standard one and regenerate
}

Prevention

Keep only IANA-standard response codes as response keys; document gateway codes in descriptions
Add a Spectral/spec-lint rule flagging response codes outside the standard set for Scala targets
Remember '0' is auto-converted to 200, so default-style '0' entries are safe

When it happens

Trigger: Generating -g scala-http4s-server from a spec whose operations declare non-standard response codes such as 299, 418-unusual variants, 499, 598, 599, or vendor codes like 277. Note code '0' is internally rewritten to 200 before the lookup, so 0 does not trigger it.

Common situations: Gateway/proxy-specific codes (499 client closed request, 599 upstream timeout) documented in internal specs; copied vendor API docs that list unofficial codes; specs that enumerate every observed status from load balancer logs.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/b2111e4d3e8b3739. Report an issue: GitHub.