Схема неуспешных ответов

[notxcain]

Во все неуспешные ответы (4xx и 5xx) нужно добавить описание ошибки и потенциальные пути ее решения. Это предложение затрагивает не только документацию но и все сервисы публичного API. Для этого есть RFC 7807. Очень хорошо описано в Zalando RESTful API Guidelines. Пример схемы:

Problem:
  type: object
  properties:
    type:
      type: string
      format: uri
      description: |
        An absolute URI that identifies the problem type.  When dereferenced,
        it SHOULD provide human-readable documentation for the problem type
        (e.g., using HTML).
      default: 'about:blank'
      example: 'https://zalando.github.io/problem/constraint-violation'
    title:
      type: string
      description: |
        A short, summary of the problem type. Written in english and readable
        for engineers (usually not suited for non technical stakeholders and
        not localized); example: Service Unavailable
    status:
      type: integer
      format: int32
      description: |
        The HTTP status code generated by the origin server for this occurrence
        of the problem.
      minimum: 100
      maximum: 600
      exclusiveMaximum: true
      example: 503
    detail:
      type: string
      description: |
        A human readable explanation specific to this occurrence of the
        problem.
      example: Connection to database timed out
    instance:
      type: string
      format: uri
      description: |
        An absolute URI that identifies the specific occurrence of the problem.
        It may or may not yield further information if dereferenced.

Пример боли с Hacking Man: участники не могли понять почему они могу получить список магазинов, а на запрос товаров магазина получают 403 Forbidden

[Lytkini]

403 сейчас в спеке вообще нет. Кто знает актуальный и полный список ошибок которые мы возвращаем? Сейчас ошибки отдаются в виде:

{
  "errors": [
    {
      "code": 2002,
      "reason": "missing",
      "subject": "deviceUuid"
    },
    {
      "code": 2002,
      "reason": "unexpected",
      "subject": "deviceUuid"
    }
  ]
}

Я правильно понимаю, что предлагается переехать на схему, аналогичную zalando?