Существует ли стандарт на ошибки / коды ошибок?

Question

Я сейчас пишу API / некоторые клиенты для шахматных игр.

Разработчики должны получить доступ к API через один скрипт (xhrframework.php) и отправить действия через GET. Возможно, что они делают некоторые ошибки, когда отправляют действия (нет PHPSESSID, нет действительного PHPSESSID, перемещение не было действительным, это не их очередь, ...).

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

1. через сообщение об ошибке на чистом английском языке
   • +: Понятно, что должна означать ошибка
   • +: можно добавить информацию, как исправить эту ошибку
   • -: сообщение может измениться, так как мой английский не очень хорош
   • -: длина сообщения сильно отличается - это может быть важно для программистов на C
2. через константу сообщения об ошибке на английском языке - что-то вроде WRONG_PHPSESSID, MISSING_PHPSESSID, INVALID_MOVE, NOT_YOUR_TURN, ...
   • +: это понятно человеку
   • 0: почти наверняка сообщение не изменится
   • -: длина сообщения может немного отличаться
3. через код ошибки с одной таблицей в документации, где программист может найти значение кода ошибки
   • +: код ошибки будет постоянным
   • +: длина каждого кода ошибки может быть одинаковой
   • -: это загадочно

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

Теперь я хотел бы знать, существует ли стандарт для сообщений об ошибках Web-API. Как другие (например, Google Maps API) решили эту проблему? Должен ли я просто выводить пустую страницу с содержанием «ОШИБКА: 004» или без заполнения «ОШИБКА: 4»?

Какие ошибки должны получать какие числа? Имеет ли смысл группировать ошибки по их номерам, например, все ошибки, начинающиеся с 1, были ошибками аутентификации, все ошибки с двумя ошибками игровой логики? Было бы лучше начать с ошибки 1 и использовать каждый номер?

API Карт Google

Если я сделаю неправильный вызов для JS-API Карт Google, он вернет Java-Script с сообщением на понятном немецком языке (как я думаю, я живу в Германии).

Google Static Maps API возвращает сообщение в виде текста на чистом английском языке, если я совершаю неправильный вызов .

Answer 1

Большинство сервисов API используют систему кодов ошибок HTTP RFC2817 с диапазонами кодов ошибок для различных типов ошибок:

1xx: Informational - Request received, continuing process 
2xx: Success - The action was successfully received, understood, and accepted 
3xx: Redirection - Further action must be taken in order to complete the request 
4xx: Client Error - The request contains bad syntax or cannot be fulfilled 
5xx: Server Error - The server failed to fulfil an apparently valid request

В контексте API вы в основном используете значения 4xx для обозначения условий ошибок, связанных с проверкой запросов. 49x обычно используются для ошибок безопасности.

Answer 2

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

[one of "ERROR" or "WARNING" or "MESSAGE"]
[error code with no spaces, eg "BAD_MOVE"]
[optional human readable string]

Таким образом, если придуман новый тип ошибки, которого старые клиенты не делаютпонимают, что они все еще могут распознать, что возвращение начинается с «ОШИБКИ», и знают, что что-то пошло не так;анализируя код ошибки (не используйте целые числа, это пустая трата времени каждого), они могут предпринять соответствующие действия, если это ошибка, которую учел программист.Наконец, если вы добавите дружественную строку для выбранных ошибок, это позволит легко представить что-то приятное пользователю или быть полезным для отладки.