server/api/utils/errors.js

  1. /**
  2.  * Reusable API errors.
  3.  *
  4.  * @module server/api/utils/errors
  5.  */
  6. const util = require('util');
  8. /**
  9.  * An API error.
  10.  *
  11.  * When thrown from an API route or middleware, an error of this type will
  12.  * automatically be serialized as JSON and the HTTP response will have the
  13.  * correct status code.
  14.  *
  15.  * @class
  16.  * @extends Error
  17.  * @property {string} name - The type of error.
  18.  * @property {number} status - The HTTP status code to respond with when this error occurs.
  19.  * @property {string} code - A code identifying the error (e.g. `category.whatWentWrong`).
  20.  * @property {string} message - A description of the problem.
  21.  */
  22. function ApiError(status, code, message) {
  24.   Error.captureStackTrace(this, this.constructor);
  26.   this.name = this.constructor.name;
  27.   this.status = status;
  28.   this.code = code;
  29.   this.message = message;
  30. }
  32. util.inherits(ApiError, Error);
  34. exports.ApiError = ApiError;
  36. /**
  37.  * Returns an HTTP 401 Unauthorized error.
  38.  *
  39.  * @param {string} code - A code identifying the error (e.g. `auth.whatWentWrong`).
  40.  *
  41.  * @param {string} message - A description of the problem.
  42.  *
  43.  * @returns {ApiError} An API error.
  44.  */
  45. exports.unauthorized = function(code, message) {
  46.   return new ApiError(401, code, message || 'Authentication is required to access this resource. Authenticate by providing a Bearer token in the Authorization header.');
  47. };
  49. /**
  50.  * Returns an HTTP 401 Unauthorized error with the `auth.missingAuthorization` code due to missing credentials.
  51.  * @returns {ApiError} An API error.
  52.  */
  53. exports.missingAuthorization = function() {
  54.   return exports.unauthorized('auth.missingAuthorization');
  55. };
  57. /**
  58.  * Returns an HTTP 401 Unauthorized error with the `auth.malformedAuthorization` code due to malformed credentials (e.g. a badly formatted Authorization header).
  59.  * @returns {ApiError} An API error.
  60.  */
  61. exports.malformedAuthorization = function() {
  62.   return exports.unauthorized('auth.malformedAuthorization', 'The Authorization header is not in the correct format. It should be "Authorization: Bearer TOKEN".');
  63. };
  65. /**
  66.  * Returns an HTTP 401 Unauthorized error with the `auth.invalidAuthorization` code due to invalid credentials (e.g. an expired JWT).
  67.  * @returns {ApiError} An API error.
  68.  */
  69. exports.invalidAuthorization = function() {
  70.   return exports.unauthorized('auth.invalidAuthorization', 'The Bearer token supplied in the Authorization header is invalid or has expired.');
  71. };
  73. /**
  74.  * Returns an HTTP 403 Forbidden error.
  75.  *
  76.  * The message defaults to "You are not authorized to access this resource. Authenticate with a user account that has more privileges.".
  77.  *
  78.  * @param {string} [code=auth.forbidden] - A code identifying the error.
  79.  *
  80.  * @param {string} [message] - A description of the problem.
  81.  *
  82.  * @returns {ApiError} An API error.
  83.  */
  84. exports.forbidden = function(code, message) {
  85.   return new ApiError(403, code || 'auth.forbidden', message || 'You are not authorized to access this resource. Authenticate with a user account that has more privileges.');
  86. };
  88. /**
  89.  * Returns an HTTP 404 Not Found error.
  90.  *
  91.  * The message defaults to "No resource was found at this verb and URI.".
  92.  *
  93.  * @param {string} [code=resource.notFound] - A code identifying the error.
  94.  *
  95.  * @param {string} [message] - A description of the problem.
  96.  *
  97.  * @returns {ApiError} An API error.
  98.  */
  99. exports.notFound = function(code, message) {
  100.   return new ApiError(404, code || 'resource.notFound', message || 'No resource was found at this verb and URI.');
  101. };
  103. /**
  104.  * Returns an HTTP 404 Not Found error due to a missing resource.
  105.  * @returns {ApiError} An API error.
  106.  */
  107. exports.recordNotFound = function(name, id) {
  108.   return exports.notFound('record.notFound', 'No ' + name + ' was found with ID ' + id + '.');
  109. };