Какой код состояния HTTP следует использовать для бизнес-ошибок при разработке API?

Question

Допустим, у меня есть конечная точка API, которая выполняет некоторую бизнес-операцию, которая может привести к множеству различных сбоев, которые не связаны напрямую с запросом.

Запрос сформирован правильно, и я не могу вернуть ошибки 4xx, но логика приложения требует, чтобы я возвращал различные сообщения об ошибках.

Теперь я хочу, чтобы клиент мог различать эти сообщения об ошибках, чтобы в зависимости от кода можно было выполнять различные действия. Я могу вернуть пользовательский JSON, например, такой:

{
  "code": 15,
  "message": "Some business error has occurred"
}

Теперь вопрос в том, какой код статуса HTTP мне следует использовать в таких случаях, если нет никакого стандартного кода, такого как Conflict или NotFound.

Кажется, что 500 InternalServerError логично, но тогда как я могу дополнительно отметить, что это не может быть повторено, если просто документировать, что заданные коды состояния невозможно повторить, так что можно повторить, если вы не получите один из тех?

Answer 1

Проконсультируйтесь RFC 7231 :

503 Сервис недоступен выглядит как потенциальный кандидат, но RFC упоминает, что это должно представлять проблему, "которая, вероятно, будет устранена после некоторой задержки". Это будет указывать клиенту на то, что он может попробовать тот же звонок позже, возможно, в нерабочее время или в выходные дни. Это не то, что вы хотите.

501 Не реализовано возможно, но в RFC упоминается "Это является соответствующим ответом, когда сервер не распознает метод запроса и не способен поддерживать его для любого ресурса. Ответ 501 кэшируется по умолчанию; «Это, похоже, не тот случай - сам метод HTTP предположительно действителен - ошибка здесь, по-видимому, происходит на уровне бизнес-правил (например, отправка в номер учетной записи, которого нет в базе данных), а не метод HTTP (GET, POST и т. д.), который вы никогда не удосужились реализовать.

Это оставляет последнего серьезного кандидата,

500 Внутренняя ошибка сервера

Код состояния 500 (Внутренняя ошибка сервера) указывает, что сервер столкнулся с неожиданным состоянием, которое помешало ему выполнить запрос.

Это код ошибки, который обычно используется для общих ситуаций «исключение произошло в приложении». 500 - лучший выбор.

Что касается того, как отличить это от ошибки «временная внутренняя проблема», вы можете включить это как часть тела HTTP - просто убедитесь, что ваш клиент может разобрать пользовательские коды!