Error Handling

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>"
        }
      }
    }
  }]
}

Error Code Glossary

Standard Error Codes

Please see below all error codes listed in detail. In general, a standard 4xx error indicates a bad request, whereas 5xx indicates a server problem. In case of a 4xx error, please check the error code glossary and for 5xx you may retry again later or contact support@caruso-dataplace.com.

HTTP Code
ReasonCode
ReasonText Additional Explanation
400 CAR.400 Bad request, please conform to the API specification.
Bad request, mandatory header parameter {} is missing. {} = [‘X-Api-Key’, ‘X-Subscription-Id’]
Bad request, please provide a non empty list of {}. {} = [‘Vehicles’ , ‘DataItems’]
Bad request, unsupported api version {}. {} = given Api version
Items {} are not covered by subscription or incorrect names provided. {} = not covered/wrong item names - comma separated
Bad request, maximum number of vehicles {} exceeded. {} = currently configured MAX_LIMIT(10)
Bad request, subscription not found.
401 CAR.401 Unauthorized request, invalid API key. Authentication failure
403 CAR.403 Request is outside of subscription validity. Authorization failure
429 CAR.429 Request limit exceeded for this plan.
500 CAR.500 Internal service failure occured. Please try again later.
502 CAR.502 Communication problem with the provider occured. Please try again later.

Custom Error Codes

These errors are embedded in a response body with standard code 200 OK.

Vehicle Error Codes

Code
Message Additional Explanation
CAR.VE.901 Incorrect VIN format.
CAR.VE.902 Vehicle indentifier type {} not supported.` The only supported indentifier is VIN
CAR.VE.903 The vehicle is not registered or the vehicle is not telematics/connected service capable.
CAR.VE.904 The vehicle is black listed.
CAR.VE.905 Consent not provided by the car owner.
CAR.VE.906 Request limit exceeded for the vehicle.
CAR.VE.907 Unexpected error on provider side, data can not be retrieved.
CAR.VE.908 No data returned by the provider.
CAR.VE.909 Internal server problem occurred, please try again later.
CAR.VE.910 Vehicle activation is pending, please try again later.
CAR.VE.911 Vehicle activation required.
CAR.VE.999 Unidentified vehicle error. Please contact the support with your transaction id. Unexpected Error

Data Item Error Codes

Code
Message Additional Explanation
CAR.DE.100 Unidentified vehicle error. Please contact the support with your transaction id. Unexpected Error
CAR.DE.101 Wrong item name, please conform to the data catalog.
CAR.DE.102 Item not covered by subscription.
CAR.DE.103 Received incompatible value from the provider.
CAR.DE.104 No data returned by the provider.
CAR.DE.105 Item is not supported for polling.