GPS Data Web Service API

Error Handling

Dealing with errors

When interacting with the service, it's possible to initiate a request that causes an error condition to occur. For example, you might try to POST an email address, but accidentally send a blank string, or an email address in an invalid format. In this case, the response have a non-successful HTTP status code:

More detailed error information

When possible (and useful), an object will be returned that gives even more detail about the nature of the error. This is most useful with the 400 and 409 HTTP Status codes, because the error object's properties correspond to the POST or PUT data, and the values tell what exactly went wrong.

PUT /rest/v2/sample HTTP/1.0
Host: mygink.com
Accept: application/json
Cookie: token=[token]
Content-type: application/json
Content-length: 463

{
    "ts": 1511148772,
    "url": "sample\/url\/",
    "trips": [
        {
            "drive_t": "02:33:08",
            "drive_dist": 187.8992
        },
        {
            "drive_t": "01:04:00",
            "drive_dist": 93.223
        },
        {
            "drive_t": "00:23:50",
            "drive_dist": 60.2523
        }
    ],
    "driver": {
        "name": "Slartibartfast",
        "occupation": "Fjord Designer",
        "speed": "R17"
    }
}
HTTP/1.0 400 Bad Request
Date: Mon, 20 Nov 2017 03:32:52 GMT
Content-type: application/json
Content-length: 52

{
    "driver": {
        "speed": "toofast"
    }
}
HTTP/1.0 409 Conflict
Date: Mon, 20 Nov 2017 03:32:52 GMT
Content-type: application/json
Content-length: 49

{
    "driver": {
        "name": "taken"
    }
}

Real-life error strings

The above examples aren't something you'll really see - they only illustrate how the properties from the error objects correspond with what was wrong in the request.

Here are the error strings you might encounter:

empty
The property must exist and have data, but the request didn't
invalid
The property must be a certain format (e.g. email address, date, IMEI), but the request sent data that didn't fit the format
taken
You'll see this with the 409 status: usually because the property must be unique, and the value you gave is taken already