oapi-codegen · ChrisJr404 · Aug 25, 2026
@@ -310,6 +310,10 @@
           "type": "boolean",
           "description": "Disable the generation of a `ContentType()` method on response objects for `ClientWithResponses`, which is otherwise generated by default."
         },
+        "client-response-error-on-unexpected-response": {
+          "type": "boolean",
+          "description": "Add a `default` case to the response switch in the generated `Parse<Operation>Response` functions that returns the sentinel `ErrUnexpectedResponse` error when the response status code and content-type match none of the responses declared in the OpenAPI specification."
+        },
         "skip-response-body-getters": {
           "type": "boolean",
           "description": "Disable the generation of `GetBody()` and `Get<TypeName>()` getter methods on response objects for `ClientWithResponses`, which are otherwise generated by default."

@@ -145,6 +145,7 @@ output-options:
       #   template: '{{.FieldName}}'
   client-response-bytes-function: false
   skip-client-response-content-type: false
+  client-response-error-on-unexpected-response: false
   skip-response-body-getters: false
   streaming-content-types: []
   # Short names for media types, used in generated type names. Keys are the

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=../../../../../configuration-schema.json
+package: optionsunexpectedresponseenabled
+output: unexpected_response.gen.go
+generate:
+  client: true
+  models: true
+output-options:
+  # outputoptions/unexpected-response/enabled: error on responses the spec does not declare.
+  client-response-error-on-unexpected-response: true
@@ -0,0 +1,10 @@
+// Package optionsunexpectedresponseenabled checks that, with
+// client-response-error-on-unexpected-response set to true, the generated
+// Parse<Operation>Response functions gain a default case that returns the
+// sentinel ErrUnexpectedResponse when the response matches none of the
+// declared responses.
+//
+// outputoptions/unexpected-response/enabled
+package optionsunexpectedresponseenabled
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ../spec.yaml
@@ -0,0 +1,41 @@
+package optionsunexpectedresponseenabled
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func newResponse(status int, contentType, body string) *http.Response {
+	h := http.Header{}
+	if contentType != "" {
+		h.Set("Content-Type", contentType)
+	}
+	return &http.Response{
+		StatusCode: status,
+		Header:     h,
+		Body:       io.NopCloser(bytes.NewReader([]byte(body))),
+	}
+}
+
+// outputoptions/unexpected-response/enabled: a response the spec does not declare
+// (here a 500) hits the generated default case and returns ErrUnexpectedResponse.
+func TestUnexpectedResponseReturnsSentinel(t *testing.T) {
+	res, err := ParseGetThingResponse(newResponse(http.StatusInternalServerError, "application/json", `{"oops":true}`))
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, ErrUnexpectedResponse), "expected ErrUnexpectedResponse, got %v", err)
+	assert.Nil(t, res)
+}
+
+// A declared response (200) is still parsed normally, with no error.
+func TestExpectedResponseParsesWithoutError(t *testing.T) {
+	res, err := ParseGetThingResponse(newResponse(http.StatusOK, "application/json", `{"id":"1","name":"rock"}`))
+	require.NoError(t, err)
+	require.NotNil(t, res.JSON200)
+	assert.Equal(t, "rock", res.JSON200.Name)
+}
@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=../../../../../configuration-schema.json
+package: optionsunexpectedresponseskipped
+output: unexpected_response.gen.go
+# client-response-error-on-unexpected-response is left UNSET — no default case is generated.
+generate:
+  client: true
+  models: true
@@ -0,0 +1,9 @@
+// Package optionsunexpectedresponseskipped checks that, with
+// client-response-error-on-unexpected-response unset (the default), the
+// generated Parse<Operation>Response functions have no default case and an
+// unexpected response yields a response object with a nil error.
+//
+// outputoptions/unexpected-response/skipped
+package optionsunexpectedresponseskipped
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ../spec.yaml