Invalid HTTP response status code

Description

OpenAPI response keys use valid HTTP status codes or default. Informational 1xx responses are valid. OpenAPI 3.0 also permits uppercase ranges from 1XX through 5XX. OpenAPI 2.0 does not define these range expressions.

Response keys help clients and API tools interpret each status. The documented status codes and response descriptions should match the API's actual behavior.

Potential impact

• The API document might not accurately describe the responses returned by the implementation.
• Code generators, documentation tools, and test tools can reject malformed response keys or handle them differently.
• A mismatch between the documentation and actual responses can cause client error handling or redirects to behave unexpectedly.

Remediation

Use codes that describe the responses the implementation actually returns. Common examples are 200, 404, and 500; default can describe responses not covered explicitly. If ranges are needed, use the uppercase OpenAPI 3.0 form. For 2.0, use individual codes or default. Check each code's meaning against the HTTP status code registry. Validate the complete document with a tool that supports its OpenAPI version, and compare it with actual API responses.

Response-key examples

These examples illustrate why response keys need both a valid format and the right meaning. They omit required elements such as the info object and are not complete OpenAPI documents. The 310 value in the second example should not be used as shown.

Invalid response keys

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "50": {
            "description": "Invalid status"
          },
          "6xx": {
            "description": "Invalid range"
          }
        }
      }
    }
  }
}

Status codes whose meaning needs review

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "OK"
          },
          "310": {
            "description": "Redirect"
          }
        }
      }
    }
  }
}

Explanation:

• Invalid response keys: 50 is not a three-digit status code, and 6xx is not an allowed HTTP status-code range.
• Status codes whose meaning needs review: 200 indicates a successful request, but 310 is not a registered standard redirect code. Choose a code such as 301 or 302 that matches the actual redirect behavior.

References

• OpenAPI 3.0.3 Responses Object
• OpenAPI 2.0 Responses Object
• IANA HTTP status code registry
• CWE-20