Errors

The API provides details for each failed request.

Error response

An error object is returned when a request fails.

{
  "success": false,
  "message": "Required values are missing.",
  "data": {
    "error": {
      "type": "user",
      "code": 400,
      "fields": {
        "username": "This value is required.",
        "password": "This value is required."
      },
      "dev_message": ""
    }
  }
}

The data.error.fields is an array of field names and their associated error messages for display in your UI.

The message is always suitable for user feedback. When the error type is user, details are provided to assist the user in recovery. Otherwise, the default "An error occurred. Please try again later." is provided.

The data.error.dev_message is a detailed error message for debugging purposes.

Error types

The data.error.type will be one of the following:

• user - An error occurred as a result of user-provided values (e.g. invalid password, required data missing).
• codebase - The request was invalid or missing required parameters that could not be provided by the user (e.g. uri, api keys, record IDs).
• system - System errors indicate there was a problem on our end.

Error codes

The data.error.code will be one of the following:

• 400 Bad Request

  • Description: The API cannot process the request because it is malformed or missing required structure.
  • Example: The client sends a request with invalid JSON, or omits a required top-level field entirely.
  • In short: “Your request is broken.”

• 401 Unauthorized

  • Description: The client is not authenticated; credentials are missing or invalid.
  • Example: The client requests their profile information without providing a valid access token.
  • In short: “You need to log in.”

• 403 Forbidden

  • Description: The client is authenticated but does not have permission for the requested action.
  • Example: A regular user attempts to delete another user's account, but only admins are allowed to do this.
  • In short: “You’re not allowed to do this.”

• 404 Not Found

  • Description: The requested API endpoint or resource does not exist.
  • Example: The client tries to fetch details for a product ID that does not exist in the database.
  • In short: “What you’re looking for isn’t here.”

• 422 Unprocessable Entity

  • Description: The API understands the request, but the data fails validation rules.
  • Example: The client submits a registration form with a password that is too short or an email address in the wrong format.
  • In short: “Your data is invalid.”

• 500 Internal Server Error

  • Description: The API encountered an unexpected error while processing the request.
  • Example: The server crashes due to a bug when trying to retrieve a list of orders.
  • In short: “Something went wrong on our end.”