Как обрабатывать ошибки в RESTful API (форматы ответов, коды статусов)?

Структура ответа об ошибке:

{
    "error": "auth_failed",
    "message": "Неверный пароль",
    "details": {"retries_left": 2}
}

HTTP-статусы:

• 400 Bad Request — неверный синтаксис (например, невалидный JSON).

• 401 Unauthorized — требуется аутентификация.

• 403 Forbidden — доступ запрещён (у пользователя нет прав).

• 404 Not Found — ресурс не существует.

• 429 Too Many Requests — слишком много запросов.

• 500 Internal Server Error — ошибка на сервере.

Реализация в Go:

func handler(w http.ResponseWriter, r *http.Request) {
    	user, err := authenticate(r)
    	if err != nil {
        	w.Header().Set("Content-Type", "application/json")
        	w.WriteHeader(http.StatusUnauthorized) // 401
        	json.NewEncoder(w).Encode(map[string]string{
            		"error": "unauthorized",
            		"message": "Требуется логин",
        	})
        	return
    	}
    	// ...
}

Рекомендации:

• Не возвращайте стектрейс в продакшене (риск утечки данных).

• Используйте стандартные коды ошибок (например, invalid_token для OAuth).

• Для валидации данных возвращайте 422 Unprocessable Entity с деталями полей:

  {
      "error": "validation_failed",
      "details": [{"field": "email", "error": "invalid_format"}]
  }

Вывод: Четкие ошибки ускоряют отладку клиента и улучшают пользовательский опыт.