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
error_data.name	WRITING_ON_READONLY_MODE, DATABASE_NOT_READY or missing
error_data	error indicates the issue when appropriate

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, CODE_DOES_NOT_MATCH, CODE_EXPIRED, ACCOUNT_HAS_NO_KEYS
error_data	error indicates the issue

JwtTokenExpired

The JWT token has expired. You should get a new token using the refresh token.

HTTP Status Code	401 Unauthorized
error_code	22
error_data.name	INCORRECT_JWT_TOKEN

RefreshTokenExpired

The refresh token has expired. Be sure to update your update the refresh token every time you use it.

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, WRONG_PARAMETER, WRONG_OP_USE, INCORRECT_USER_ID_TYPE, INCORRECT_ITEM_ID_TYPE, INCORRECT_SESSION_ID_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, DUPLICATED_SESSION_ID
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, INCORRECT_ACCOUNT, SSO_AUTHENTICATION_FAIL INCORRECT_FRONTEND_SESSION_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, CONNECTION_NOT_FOUND, ORGANIZATION_NOT_FOUND, TABLE_NOT_FOUND, RESOURCE_NOT_FOUND, SCENARIO_NOT_FOUND, SAML_NOT_FOUND, TABLE_IS_EMPTY
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