Коды ошибок

Для возврата ошибок, используем стандарт ProblemDetails:
HTTP/1.1 200 OK
Content-Type: application/problem+json

{
"type": "https://help.myproject.ru/error-codes/pay10001",
  "title": "Недостаточно денег на счете",
  "status": 200,
  "detail": "Ваш текущий баланс 300. Стоимость покупки 500.",
  "code": "pay10001",
  "id": "8273f48b-d8d8-4e0e-9711-d52e3b7ff8b8",
  "userId": "aabe69e9-bb0a-47c3-8b82-890785b9da7a",
  "orderId": "efdc93a1-04fb-4cc8-8d2c-e693972f7429",
"cost": 500,
"balance": 300
}

Пройдемся по каждому полю.
type - Ссылка на документацию по коду ошибки
status - Статус код HTTP ответа, повторяет заголовок. Добавлен для удобства клиента
title - Короткое и понятное человеку описание проблемы. Оно должно быть статичным и зависит только от кода ошибки
detail - Детальное описание ошибки, которое должно помочь устранить проблему

Расширение спецификации для всех ответов:

id - Уникальный идентификатор ошибки. Он же должен присутствовать в логах, чтобы найти информацию о проблеме.
code - Код ошибки.

Остальные поля в примере - это расширение под конкретный ответ, они добавляются как key-value в корневую ноду.