# unambiguous-response-codes

Source: https://apigenie.pl/docs/linter/openapi/rules/unambiguous-response-codes

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: Recommended at error, Strict at error, All at error.

This rule checks that no operation declares both a range, such as `2XX`, and a code of that range,
such as `204`.

## Rule details

OpenAPI gives a code precedence over its range, but a reader does not know that, and a response
declared twice, once as `204` and once as part of `2XX`, raises the question which description,
body and headers apply. Tools differ too: a mock server picks one, a generated client may
deserialize the other.

The rule reports `Operation response codes are ambiguous` on the response that overlaps an
earlier one. Turn it off when the API treats a range as the default and a code as its override on
purpose.

## Examples

**Good**. A range and a code of another range.

```yaml
paths:
  /users:
    get:
      responses:
        "103":
          description: Early hints for the resources the page needs.
        "2XX":
          description: A list of users.
```

**Bad**. `204` is in `2XX`.

```yaml
paths:
  /users:
    get:
      responses:
        "2XX":
          description: A list of users.
        "204":
          description: No content.
```
