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:

• 401: Authenticate: you haven't authenticated your request
• 403: Not Authorized: you can't access the data
• 400: Bad Request: some property is incorrect
• 409: Conflict: your request would be valid, but existing data conflicts with your input
• 500: Server Error: it's not your fault, a problem happened on our side
• 503: Temporarily Unavailable: the service is temporarily out for maintenance purposes

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": 1371704833,
    "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: Thu, 20 Jun 2013 05:07:13 GMT
Content-type: application/json
Content-length: 52

{
    "driver": {
        "speed": "toofast"
    }
}

HTTP/1.0 409 Conflict
Date: Thu, 20 Jun 2013 05:07:13 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