Common errors

The APIv2 client can raise exceptions for many reasons. It is advisable to write code that gracefully handles all possible API exceptions. The APIv2 makes a distinction between 3 types of errors:

Network errors

Problems with intermittent communication between client and server can lead to Network Errors. They return low-level errors, like socket or timeout exceptions. When intermittent problems occur, clients are usually left in a state where they don’t know whether or not the server received the request.

Clients should retry the same requests, ideally according to an exponential back off schedule, until they’re able to receive a result from the server. When the failures follow a repetitive pattern, it is very likely a chronic (network) problem.

Content errors

Content error occurs when the API request is invalid. Content errors can be recognized by its HTTP response with a 4xx code. The reason why a certain error occurs is added to the response data.

Integrations should correct the original request, you need to find the part of the request that was wrong and correct it. The response can give you a hint of what part is wrong. You can use our API reference guide to add the correct headers to your request. Two common errors occur when you forget to add a certain header or you enter the wrong or invalid public Id in a certain header. Examples of these responses are shown below:

{
    "data": [
        {
            "message": "Required header",
            "propertyName": "Api-Company"
        }
    ],
    "moreAfter": null,
    "status": "error",
    "type": "Error"
}

{
    "data": [
        {
            "message": "Invalid value",
            "propertyName": "Api-Company"
        }
    ],
    "moreAfter": null,
    "status": "error",
    "type": "Error"
}

Authorization errors

At times, authorization errors can also occur:

Invalid value - Authorization: this error occurs mostly in situations where the bearer token used to perform the API call has expired, or if the credentials used to create it were incorrect. To avoid this error, it is necessary to generate a new and valid bearer token.
2FA is required: if a user uses their credentials to generate a bearer token and does not use an OTP to do so, this role could occur in case he was assigned a role that has the Enforce two-factor authentication checkbox selected in a Company. This can be seen in Roles > Edit role > Log in > Enforce two-factor authentication. To fix this, the user should generate a bearer token by adding their OTP to the credentials. It is also possible for a Platform Admin to deactivate the enforcing of 2FA, but this could be a potential security risk, and therefore not usually recommended.
Value is too short - Authorization: the bearer token is too short and something went wrong during its generation. It is recommended to generate it once more by paying attention to the credentials.
Value is too long - Authorization: the bearer token is too long and something went wrong during its generation. The same solution for the previous error applies: it is recommended to generate it once more by paying attention to the credentials.
Authorization must start with a type and have credentials - Authorization: the bearer token was probably badly encrypted. There might be a space or an invalid character in it that causes the error, therefore it is recommended to generate the bearer token anew.
Value does not match regex expression - Authorization: something probably went wrong with the encryption of the bearer token, which does not fit the regex expression required for authentication. The solution would be trying to generate the bearer token again.

{
    "type": "Error",
    "data": [
        {
            "message": "Invalid value",
            "propertyName": "Authorization"
        }
    ],
    "moreAfter": null,
    "status": "error"
}

{
    "type": "Error",
    "data": [
        {
            "message": "2FA is required"
        }
    ],
    "moreAfter": null,
    "status": "error"
}

{
  "type": "Error",
  "data": [
    {
      "message": "Value is too short",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}

{
  "type": "Error",
  "data": [
    {
      "message": "Value is too long",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}

{
  "type": "Error",
  "data": [
    {
      "message": "Authorization must start with a type and have a credentials",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}

{
  "type": "Error",
  "data": [
    {
      "message": "Value does not match regex expression",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}

Server errors

These errors can occur when there is a problem with one of the IXON servers or when a request takes more than 60 seconds. We strive to make these errors as rare as possible, however, we advise to be able to handle them when they do arise. Server errors can be recognized by an HTTP response with a 5xx code.

When a 500 Internal Server Error occurs, it is most likely during a production incident or the remediation of a production incident. We continually monitor our servers and try to resolve any problems as soon as possible. In the case of a 504 Gateway Timeout and a response time of more than 60 seconds, the error can be prevented by minimizing the scope of the request.