# standard-response-errors

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

This rule ensures that bodies for "error" responses are adhere to the same
convention.

## Rule Details

Having errors formatted in the same way significantly simplifies their
handling.

The `standard-response-errors` rule is designed to ensure that the bodies of
all responses for 4xx and 5xx codes in a schema adhere to the same convention.

Currently supported conventions are:

- Problem JSON. This convention provides a standardized format for sending
  details about errors in HTTP APIs, enhancing the consistency and
  interoperability of the API's structure.
- JSON API. By this convention, a response body is an array of Error objects,
  as defined in JSON:API specification.

## Configuration

The configuration is a single string representing the desired convention.

Currently supported values are:

- `problem-json` - [Problem
  JSON](https://datatracker.ietf.org/doc/html/rfc7807). This is the default
  value
- `json-api` - convention, where a response body is a list of [JSON:API Error
  objects](https://jsonapi.org/format/#error-objects)

**Configuration Example**

```yaml
lint:
  standard-response-errors:
    - error
    - problem-json
```

## Examples

**Good**.

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

**Bad**.

```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. The response must use the
`application/vnd.api+json` media type, and its schema must be an object whose
`errors` property is an array of objects.

```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
```

## When Not to Use It

When your team or organisation has different conventions for formatting
errors.

## Compatibility

This rule is compatible with all OpenAPI 3.x versions.