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 |
Unauthorized request, IP not whitelisted. | Authorization 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. |