comment errors according to apidoc, add new tests and fix existing ones

website/src/libs/api-v3/errors.js

@@ -7,8 +7,17 @@ export class CustomError extends Error {
   }
 }
 
-// NotAuthorized error with a 401 http error code
-// used when a request is not authorized
+/**
+ * @apiDefine NotFound
+ * @apiError NotFound The client is not authorized to make this request.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 401 Unauthorized
+ *     {
+ *       "error": "NotAuthorized",
+ *       "message": "Not authorized."
+ *     }
+ */
 export class NotAuthorized extends CustomError {
   constructor (customMessage) {
     super();
@@ -18,10 +27,18 @@ export class NotAuthorized extends CustomError {
   }
 }
 
-// BadRequest error with a 400 http error code
-// used for requests not formatted correctly
-// TODO use for validation errors too?
-export class BadRequest extends CustomError {
+/**
+ * @apiDefine BadRequest
+ * @apiError BadRequest The request wasn't formatted correctly.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 400 Bad Request
+ *     {
+ *       "error": "BadRequest",
+ *       "message": "Bad request."
+ *     }
+ */
+ export class BadRequest extends CustomError {
   constructor (customMessage) {
     super();
     this.name = this.constructor.name;
@@ -37,25 +54,35 @@ export class BadRequest extends CustomError {
  * @apiErrorExample Error-Response:
  *     HTTP/1.1 404 Not Found
  *     {
- *       "error": "NotFound"
+ *       "error": "NotFound",
+ *       "message": "Not found."
  *     }
  */
 export class NotFound extends CustomError {
   constructor (customMessage) {
     super();
     this.name = this.constructor.name;
-    this.httpCode = 401;
+    this.httpCode = 404;
     this.message = customMessage || 'Not found.';
   }
 }
 
-// InternalError error with a 500 http error code
-// used when an unexpected, internal server error is thrown
+/**
+ * @apiDefine InternalServerError
+ * @apiError InternalServerError An unexpected error occurred.
+ *
+ * @apiErrorExample Error-Response:
+ *     HTTP/1.1 500 Internal Server Error
+ *     {
+ *       "error": "InternalServerError",
+ *       "message": "An unexpected error occurred."
+ *     }
+ */
 export class InternalServerError extends CustomError {
   constructor (customMessage) {
     super();
     this.name = this.constructor.name;
     this.httpCode = 500;
-    this.message = customMessage || 'Internal server error.';
+    this.message = customMessage || 'An unexpected error occurred.';
   }
 }

website/src/middlewares/api-v3/errorHandler.js

@@ -10,6 +10,16 @@ import {
 export default function errorHandler (err, req, res, next) {
   if (!err) return next();
 
+  // Log the original error with some metadata
+  let stack = err.stack || err.message || err;
+
+  logger.error(stack, {
+    originalUrl: req.originalUrl,
+    headers: req.headers,
+    body: req.body,
+    fullError: err,
+  });
+
   // In case of a CustomError class, use it's data
   // Otherwise try to identify the type of error (mongoose validation, mongodb unique, ...)
   // If we can't identify it, respond with a generic 500 error
@@ -38,16 +48,6 @@ export default function errorHandler (err, req, res, next) {
     responseErr = new InternalServerError();
   }
 
-  // Log the original error with some metadata
-  let stack = err.stack || err.message || err;
-
-  logger.error(stack, {
-    originalUrl: req.originalUrl,
-    headers: req.headers,
-    body: req.body,
-    fullError: err,
-  });
-
   // TODO unless status >= 500 return data attached to errors
   return res
     .status(responseErr.httpCode)