# standard-response-errors

Source: https://apigenie.pl/docs/linter/openapi/rules/standard-response-errors

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

This rule checks that every 4xx and 5xx response has the error format of one convention, Problem
Details (RFC 9457) unless configured otherwise.

## Rule details

A client handles errors in one place when every error has the same shape; with one shape per
operation, it handles them in each call, or not at all. The conventions the rule knows:

- `problem-json`, [Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc9457):
  the response has the `application/problem+json` media type, and its schema is an object with the
  properties `type` (a string with `format: uri`), `title` (a string), `status` (an integer),
  `detail` (a string) and `instance` (a string with `format: uri`).
- `json-api`, the [JSON:API error objects](https://jsonapi.org/format/#error-objects): the
  response has the `application/vnd.api+json` media type, and its schema is an object whose
  `errors` property is an array of objects.

The rule reports `Response must use Problem JSON format` or `Response must use JSON:API error
format` when the media type is missing, and `Response must use correct Problem JSON schema` or
`Response must use correct JSON:API error schema` when the schema is not the one above. It is in
the `strict` and `all` rulesets; turn it off when the API has an error format of its own.

## Configuration

A convention name, `problem-json` or `json-api`. `problem-json` by default.

**Configuration example**. JSON:API errors.

```yaml
commands:
  lint:
    rules:
      standard-response-errors:
        - error
        - json-api
```

## Examples

**Good**. A Problem Details response.

```yaml
paths:
  /users:
    get:
      responses:
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    format: uri
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
                  instance:
                    type: string
                    format: uri
```

**Bad**. An error shape of its own.

```yaml
paths:
  /users:
    get:
      responses:
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
```

**Good**. With the `json-api` convention.

```yaml
paths:
  /users:
    get:
      responses:
        "400":
          description: Bad Request
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                        title:
                          type: string
                        detail:
                          type: string
```
