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. In this section, you will find generic errors and errors belonging to more specific issues, which will be shown in different sub-sections.

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.
```
{
    "type": "Error",
    "data": [
        {
            "message": "Invalid value",
            "propertyName": "Authorization"
        }
    ],
    "moreAfter": null,
    "status": "error"
}
```
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.
```
{
    "type": "Error",
    "data": [
        {
            "message": "2FA is required"
        }
    ],
    "moreAfter": null,
    "status": "error"
}
```
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.
```
{
  "type": "Error",
  "data": [
    {
      "message": "Value is too short",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}
```
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.
```
{
  "type": "Error",
  "data": [
    {
      "message": "Value is too long",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}
```
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 again.
```
{
  "type": "Error",
  "data": [
    {
      "message": "Authorization must start with a type and have a credentials",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}
```
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": "Value does not match regex expression",
      "propertyName": "Authorization"
    }
  ],
  "moreAfter": null,
  "status": "error"
}
```

SSO-related errors

In this sub-section, you will find errors related to Single Sign-On actions.

SSO is required: this error can have multiple causes:
- The email of the user does not match with the one belonging to the SSO Provider.
- The user is not authenticated with SSO in the target Company.
- If you are implementing a custom SSO login flow for a domain with a custom URL, it is possible that you are not using the correct identityProviderPublicId in the API call's implementation. To fix this issue, you should check this sub-section on the related tutorial page.
```
{
  "type": "Error",
  "data": [
    {
      "message": "SSO is required"
    }
  ],
  "moreAfter": null,
  "status": "error"
}
```
Invalid value - ssoAuthentication.code / ssoAuthentication.state: this error can occur when, for some reason, the code or state fields necessary to generate an SSO access token have not been generated correctly. It is recommended to check the user's credentials and a correct registration on the Company that enforces the SSO.
- In case of a custom domain: particularly, this error can show up even when using the correct identityProviderPublicId in the code implementation. What triggers it is lack of the Api-Branding header in the request body of the SsoAuthenticationRequestList endpoint if the "Enforce Single Sign-On" option is toggled on the user's role in the Admin: as a consequence, the API cannot check if the identityProviderPublicId can be used in the custom domain, whose value is stored in the Api-Branding header (the URL of the domain). The solution consists of adding this header to the request body and assign to it the correct custom domain URL. For more details about this, check the yellow note in this code tutorial.

{
  "type": "Error",
  "data": [
    {
      "message": "Invalid value",
      "propertyName": "ssoAuthentication.code"
    },
    {
      "message": "Invalid value",
      "propertyName": "ssoAuthentication.state"
    }
  ],
  "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.