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

В настоящее время я пишу API/некоторые клиенты для шахматных игр.

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

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

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

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

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

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

API Карт Google

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

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

Ответ 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 обычно используются для условий безопасности.

Ответ 2

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

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

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

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