How to fix an invalid response code key in OpenAPI

Keys under an OpenAPI responses object cannot contain a reason phrase such as 200 OK. Use a quoted three-digit HTTP status code, one of the supported uppercase ranges, or default.

Broken YAML

The 200 OK key is a label, not a valid response key:

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        200 OK:
          description: Service is healthy

Why it fails

The Responses Object accepts exact HTTP status codes, the five uppercase wildcard ranges 1XX through 5XX, default, and specification extensions that start with x-. A label such as success, 200 OK, or lowercase 2xx does not match those fields.

The response description is where you put the reason or result text. Keep the map key machine-readable.

Corrected YAML

Use the exact status code as a quoted YAML key:

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        '200':
          description: Service is healthy

Use default only when one Response Object must cover status codes that have no explicit or range entry. An explicit code takes precedence over a matching range.

OpenAPI 3.0 vs 3.1

The valid key forms are the same in OpenAPI 3.0 and OpenAPI 3.1. Both versions allow exact codes, uppercase ranges such as 2XX, and default. Both specifications require exact response code fields to be quoted for JSON and YAML compatibility.

responses:
  '201':
    description: Created
  4XX:
    description: Client error
  default:
    description: Unexpected response

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The Sourced browser validator checks response presence and descriptions, but it does not currently validate response key syntax. Use the OpenAPI-aware CLI command for this error.