Error Model for API Requests

Our platform uses the standard HTTP error codes to indicate whether an API request from a consumer was successfully executed or when an error occurred. We expose errors in two models: the standard error model which follows the HTTP error codes and a customized error model.

Standard Error Codes

A standard error code is returned when a request fails in its entirety – this can be due to a consumer initiated error or a server side error. The following is an example of a standard error where the reasonCode follows the standard HTTP code and reasonText provides a human readable reason text.

HTTP/1.1 400 Bad Request
Content-Length: 183
Content-Type: application/json;charset=UTF-8

{
  "reasonCode" : "<error-code>",
  "reasonText" : "<error-text>",
  "url" : "<requested-url>",
  "method" : "<http-method>"
}

Custom Error Codes

A custom vehicle level or dataitem level error occurs when the request does not fail in its entirety but for requesting data for a certain vehicle or a certain data item of the vehicle. These errors are embedded in a response body with standard code 200 OK.

Following is an example of a vehicle error where code follows a custom convention and message is a human readable text explaining the problem.

{
  "version": "1.0",
  "deliveredAt": "2019-03-21T11:39:06.881+01:00",
  "inVehicleData": [
    {
      "identifier": {
        "type": "VIN",
        "value": "123456789102"
      },
      "error": {
        "code": "<error-code>",
        "message": "<error-message>"
      }
    }
  ]
}

Following is an example for a dataitem error where code follows a custom convention and message is a human readable text explaining the problem

{
  "version": "1.0",
  "deliveredAt": "2019-03-21T11:39:06.881+01:00",
  "inVehicleData": [{
    "identifier": {
      "type": "VIN",
      "value": "123456789102"
    },
    "response": {
      "dtc": {
        "error": {
          "code": "<error-code>",
          "message": "<error-message>"
        }
      }
    }
  }]
}