Skip to content
Last updated

operation-4xx-response

Ensures that every operation in your API document has at least one error (400-499) HTTP response defined.

OASCompatibility
2.0✅
3.0✅
3.1✅
3.2✅

API design principles

Every operation should have a 400-499 (problem) HTTP response. After all, what API doesn't have a problem from time to time?

In practice, some APIs do not return error responses. This design is based on an old-school belief that all responses, including errors, should return HTTP 200 OK. While this thinking has mostly changed (for the better in our opinion), it does still exist. If your organization believes every API should only return HTTP 200 OK, then disable this rule, or even create an opposite rule to error on any defined 4XX responses.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default warn (in recommended configuration).
validateWebhooksbooleanDetermines if responses inside webhooks are validated. Default false.
excludedMethods[string]List of HTTP methods (case-insensitive) to skip during validation. Default [].

An example configuration:

rules:
  operation-4xx-response: error

The following example enables validation of responses inside webhooks:

rules:
  operation-4xx-response:
    severity: error
    validateWebhooks: true

The following example skips operations that use the HEAD or OPTIONS method:

rules:
  operation-4xx-response:
    severity: error
    excludedMethods: [head, options]

Excluded methods also apply to callback operations and, when validateWebhooks is enabled, to webhook operations.

Examples

Given this configuration:

rules:
  operation-4xx-response: error

Example of incorrect operation response:

post:
  responses:
    '200':
      $ref: ../components/responses/Success.yaml

Example of correct operation response:

post:
  responses:
    '200':
      $ref: ../components/responses/Success.yaml
    '400':
      $ref: ../components/responses/Problem.yaml

Resources

operation-description