Errors

All API methods in Viskan API follow the same error handling. Note that some older APIs might return additional data that is not included in this specification. That data is deprecated and should be avoided.

400 Bad Request

This is the primary error that the Viskan API utilize. The response body includes an errorCode that you can use to perform logic against the error. The API also provides a message, which is only intended for the developer building the integration. Do not directly expose this to any user. In some errors, the API also provide a data object, with additional contextual information about the error. Here is an example of the structure:

{
  "errorCode": "unknown-price-lookup-number",
  "message": "The given price lookup number (PLUNO) was not found",
  "data": {
    "priceLookupNumber": "ABC123"
  }
}

On top of that, some APIs can return multiple errors at once. In those cases, there is also a moreErrors array, containing the other errors. It is completely fine to focus on the primary error. Here is an example of the structure:

{
  "errorCode": "unknown-price-lookup-number",
  "message": "The given price lookup number (PLUNO) was not found",
  "data": {
    "priceLookupNumber": "ABC123"
  },
  "moreErrors": [
    {
      "errorCode": "another-error",
      "message": "Some other error message"
    }
  ]
}

You will find possible error codes for each API method when you navigate the API reference, under the "Response" section. There is a tab section where you can switch between successful API response (2xx) and failed API response (400).

Note that in some APIs, the response body for errors might contain additional fields, such as the errors array. This is obsolete, and you should avoid using that. Please keep to the documented structure above.

401 Unauthorized

This error is returned when there is something wrong with the authentication. The API simply cannot understand who is making the request. This can happen if you haven't supplied the Authorization header, or if it is incorrect for some reason. If you did pass an Authorization, the returned header WWW-Authenticate should describe what is wrong.

403 Forbidden

This error can happen for two reasons. One of the reasons is related to CORS (Cross-Origin Resource Sharing). Viskan API has CORS disabled, so you cannot call Viskan API from the browser. If you attempt to do so, you will get a 403 Forbidden status back.

The other reason why 403 can happen is when there is something wrong with the authorization. The main cause for this is that you are trying to call an API method that requires a scope that your token does not have access to. This is also described in the WWW-Authenticate header.

404 Not Found

This error only happens when you are trying to call an API URL that do not exist. The API never return 404 Not Found when the API method exists, but the resource it is trying to load was not found. Then the API return a regular 400 Bad Request, with an error code describing the problem.

500 Internal Server Error

This error indicates that Viskan have done something wrong on their end. The error should be logged in our logging stack, but if there is something more pressing, please reach out to Viskan and preferrably supply us with the X-Correlation-ID (returned as a header, read more about tracing here) and the time when the API call was made.