Символические или числовые коды ошибок в веб-интерфейсе API

В настоящее время я работаю над новым проектом, который должен предоставить веб-интерфейс. Конечно, есть много случаев, когда запрашиваемая операция терпит неудачу, и API должен сообщать о причинах этого сбоя.

Раньше я использовал традиционный способ, когда ответ содержит числовой код ошибки и более удобное для пользователя сообщение об ошибке, но сохранение списка кодов ошибок и сопоставления между моими кодами и внутренними исключениями было немного разочаровывающим.

Я думал, что было бы удобнее использовать символические коды ошибок, например, генерируемые из имен исключений.

Я вижу следующие преимущества этой идеи:

  • Нет необходимости в сопоставлении с исключениями по номерам.
  • Невозможно назначить одинаковые коды ошибок для разных типов ошибок (в моем случае – исключения).
  • Код ошибки становится более информативным для разработчика, который будет использовать API сам по себе.

И недостатки:

  • Выявление имен исключений может быть не очень хорошей идеей с точки зрения инкапсуляции.
  • Так как коды ошибок в основном используются клиентскими приложениями API для определения типа ошибки, сравнение строки дороже.
  • Нет необходимости в центральном исключении -> регистр errcode увеличивает шансы пропустить некоторые коды ошибок в документации.

Итак, что лучше использовать: символические или числовые коды ошибок?