5.2.7. Throwing and Handling Errors

In this guide, you'll learn how to throw errors in your Medusa application, how it affects an API route's response, and how to change the default error handler of your Medusa application.

Throw MedusaError#

When throwing an error in your API routes, middlewares, workflows, or any customization, throw a MedusaError, which is imported from @medusajs/framework/utils.

The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.

For example:

Code
1import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"2import { MedusaError } from "@medusajs/framework/utils"3
4export const GET = async (5  req: MedusaRequest,6  res: MedusaResponse7) => {8  if (!req.query.q) {9    throw new MedusaError(10      MedusaError.Types.INVALID_DATA,11      "The `q` query parameter is required."12    )13  }14
15  // ...16}

The MedusaError class accepts in its constructor two parameters:

  1. The first is the error's type. MedusaError has a static property Types that you can use. Types is an enum whose possible values are explained in the next section.
  2. The second is the message to show in the error response.

Error Object in Response#

The error object returned in the response has two properties:

  • type: The error's type.
  • message: The error message, if available.
  • code: A common snake-case code. Its values can be:
    • invalid_request_error for the DUPLICATE_ERROR type.
    • api_error: for the DB_ERROR type.
    • invalid_state_error for CONFLICT error type.
    • unknown_error for any unidentified error type.
    • For other error types, this property won't be available unless you provide a code as a third parameter to the MedusaError constructor.

MedusaError Types#

TypeDescriptionStatus Code

DB_ERROR

Indicates a database error.

500

DUPLICATE_ERROR

Indicates a duplicate of a record already exists. For example, when trying to create a customer whose email is registered by another customer.

422

INVALID_ARGUMENT and UNEXPECTED_STATE

Indicates an error that occurred due to incorrect arguments or other unexpected state.

500

INVALID_DATA

Indicates a validation error.

400

UNAUTHORIZED

Indicates that a user is not authorized to perform an action or access a route.

401

NOT_FOUND

Indicates that the requested resource, such as a route or a record, isn't found.

404

NOT_ALLOWED

Indicates that an operation isn't allowed.

400

CONFLICT

Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored for a default message.

409

PAYMENT_AUTHORIZATION_ERROR

Indicates an error has occurred while authorizing a payment.

422

Other error types

Any other error type results in an unknown_error code and message.

500


Override Error Handler#

The defineMiddlewares function used to apply middlewares on routes accepts an errorHandler in its object parameter. Use it to override the default error handler for API routes.

NoteThis error handler will also be used for errors thrown in Medusa's API routes and resources.

For example, create src/api/middlewares.ts with the following:

src/api/middlewares.ts
7import { MedusaError } from "@medusajs/framework/utils"8
9export default defineMiddlewares({10  errorHandler: (11    error: MedusaError | any, 12    req: MedusaRequest, 13    res: MedusaResponse, 14    next: MedusaNextFunction15  ) => {16    res.status(400).json({17      error: "Something happened.",18    })19  },20})

The errorHandler property's value is a function that accepts four parameters:

  1. The error thrown. Its type can be MedusaError or any other thrown error type.
  2. A request object of type MedusaRequest.
  3. A response object of type MedusaResponse.
  4. A function of type MedusaNextFunction that executes the next middleware in the stack.

This example overrides Medusa's default error handler with a handler that always returns a 400 status code with the same message.

Was this chapter helpful?
Edit this page