How can I handle and identify errors returned from the API?

In this guide we will show how errors are returned from the API and what types they are.

Prerequisites

To perform this guide you will need to get an authentication token for your company from SMOC.AI. At this time there is no direct way to get this yourself but it’s being worked on.

In this guide we will use the token

XDaNkCDLpUcY4OVWBkAwyOdn

as the value to simulate having a real token available.

All data returned in this guide is test data only.

Finally you are going to need the command line curl, a similar GUI tool or your favorite programming language to perform the calls. In our examples we will lean on the use of curl for our examples.

Errors

There are two main types of errors returned. Errors have the following layout:

{
  "code": "validation",
  "message": "user with email user2@acme.com not found",
  "errors": [
    {
      "code": "validation",
      "paths": [
        "email"
      ],
      "message": [
        {
          "locale": "en",
          "message": "user with email user2@acme.com not found"
        }
      ]
    }
  ]
}

The code can be one of the following values:

Name	Description
`validation`	A validation error.
`auth_not_authorized`	The calling token is not authorized for this call.
`auth_invalid_token`	The token is an invalid token.
`unknown`	An unknown error happened.

The message field contains a high level description of the error.

The errors list will contain one or more errors describing the individual problems encountered. Say if the endpoint is validating the input it might return multiple errors for basica validation of input such as a missing field or badly formatted field.

Lets have a look at one individual error entry.

{
  "code": "validation",
  "paths": [
    "email"
  ],
  "message": [
    {
      "locale": "en",
      "message": "user with email user2@acme.com not found"
    }
  ]
}

The code field can be the same values as the table above.

The paths list will list the fields involved in the error. In this case the email field passed in triggered the error.

Finally, the message field contains a more detailed textual error where each entry is encoded with a locale for the language used to describe the error. There could potentially be multiple translations in the error message returned. But for now we only support English out of the box.