Error Handling

The Crossing Minds API is using multiple level of error identification. This allows clients to implement both simple management system together with a fine error handling.

  • At the highest level errors are identified by the HTTP status code;

  • More specific identification can be implemented from the error_code in the payload;

  • Even more specific identification can be implemented from the error_data.name in the payload.

Example

Let’s use the following request as an example, attempting to create or update three items:

$ curl -X PUT https://api.crossingminds.com/items-bulk/ -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "items": [ \
      {"item_id": "11111", "price": 9.99, "tags": ["family", "sci-fi"]}, \
      {"item_id": "22222", "price": 5.19, "tags": ["drama", "sci-fi"]}, \
      {"item_id": "11111", "price": 4.49, "tags": ["family"]} \
    ]}'

With such a request, you might receive the following error as a response:

ERROR RESPONSE
HTTP/2 400
content-type: application/json
vary: Accept, Origin
allow: GET, HEAD, OPTIONS
date: Wed, 1 Jan 2020 20:00:00 GMT
via: 1.1 google
alt-svc: clear

{
  "error_code": 42,
  "error_name": "DuplicatedError",
  "message": "The item 11111 is duplicated",
  "error_data": {
    "type": "item",
    "key": 11111,
    "name": "DUPLICATED_ITEM_ID"
  }
}
  • This response has an HTTP status code 400 Bad Request, which indicates a request error. We should not retry the request but instead look deeper for find what is wrong.

  • the payload has an error_code of 42 which indicates DuplicatedError.

  • the payload has an error_data.name of DUPLICATED_ITEM_ID telling us that some item ID is duplicated in the request. Indeed it is an error to attempt creating the same item multiple times in the same request.

List of Errors

In this document you will find all possible error codes and their description.

ServerError

The server encountered an internal error. You may be able to retry your request, but this usually indicates an error on the API side that require support.

HTTP Status Code

500 Internal Server Error or 502 Bad Gateway

error_code

0 or missing

ServerUnavailable

The server is currently unavailable, please try again later. We recommend employing an exponential backoff retry scheme.

HTTP Status Code

503 Service Unavailable

error_code

1 or missing

TooManyRequests

The amount of requests exceeds the limit of your subscription.

HTTP Status Code

429 Too Many Requests

error_code

2

error_data.name

RATE_LIMIT_OVERFLOW

error_data

retry_after contains the minimum of time to wait

AuthError

Cannot perform authentication.

HTTP Status Code

401 Unauthorized

error_code

21

error_data.name

INCORRECT_PASSWORD, ACCOUNT_NOT_VERIFIED, INCORRECT_REFRESH_TOKEN, ACTIVATION_CODE_DOES_NOT_MATCH

error_data

error indicates the issue

JwtTokenExpired

The JWT token has expired.

HTTP Status Code

401 Unauthorized

error_code

22

error_data.name

INCORRECT_JWT_TOKEN

RefreshTokenExpired

The refresh token has expired

HTTP Status Code

401 Unauthorized

error_code

28

error_data.name

REFRESH_TOKEN_EXPIRED

WrongData

There is an error in the submitted data.

HTTP Status Code

400 Bad Request

error_code

40

error_data.name

WRONG_DATA_TYPE

error_data

error indicates the issue

DuplicatedError

Some resource is duplicated.

HTTP Status Code

400 Bad Request

error_code

42

error_data.name

DUPLICATED_USER_ID, DUPLICATED_ITEM_ID, DUPLICATED_USER_PROPERTY, DUPLICATED_ITEM_PROPERTY, TASK_ALREADY_RUNNING

error_data

type and key indicates the duplicated resource

ForbiddenError

You do not have enough permissions to access this resource.

HTTP Status Code

403 Forbidden

error_code

50

error_data.name

INCORRECT_ROLE, INCORRECT_FRONTEND_USER_ID

error_data

error indicates the issue

NotFoundError

Some resource does not exist.

HTTP Status Code

404 Not Found

error_code

60

error_data.name

USER_NOT_FOUND, ITEM_NOT_FOUND, USER_PROPERTY_NOT_FOUND, ITEM_PROPERTY_NOT_FOUND, ACCOUNT_NOT_FOUND, DATABASE_NOT_FOUND

error_data

type and key indicates the missing resource

MethodNotAllowed

The HTTP method is not allowed.

HTTP Status Code

405 Method Not Allowed

error_code

70

error_data.name

HTTP_METHOD_NOT_ALLOWED