Error handling

Strapi has a standard format for errors that can be returned by the REST and GraphQL APIs or thrown by the customized parts of the Strapi backend.

Receiving errors

Errors are included in the response object with the error key and include information such as the HTTP status code, the name of the error, and additional information.

REST errors

Errors thrown by the REST API are included in the response that has the following format:

{
  "data": null,
  "error": {
    "id?": "", // Autogenerated id that can be transmitted and followed along the stack
    "status": "", // HTTP status
    "name": "", // Strapi error name ('ApplicationError' or 'ValidationError')
    "message": "", // A human reable error message
    "meta": {
      // error info specific to the error type
    }
  }
}

GraphQL errors

Errors thrown by the GraphQL API are included in the response that has the following format:

{
  "data": null,
  "error": {
    "id?": "", // Autogenerated id that can be transmitted and followed along the stack
    "status": "", // HTTP status
    "name": "", // Strapi error name ('ApplicationError' or 'ValidationError')
    "message": "", // A human reable error message
    "meta": {
      // error info specific to the error type
    }
  }
}

Throwing errors

The recommended way to throw errors when developing any custom logic with Strapi is to have the controller add a badRequest object to the context (i.e. ctx) based on Koa's (opens new window) context. This ctx.badRequest object should contain error information that follows the proper format (see receiving errors).

Services don't have access to the controller's ctx object. If services need to throw errors, these need to be caught by the controller, that in turn is in charge of sending the proper ctx.badRequest along with the response.