Errorception logo

Painless JavaScript Error Tracking

Contents

Were you looking for the client-side API docs?

Errorception HTTP API

This document outlines how to use the Errorception API. This is a very early cut of the API, and I would love feedback. Get in touch with me at [email protected].

Outline

All API access is over HTTPS only. The API is available at api.errorception.com. The server only speaks JSON.

$ curl -i https://api.errorception.com/
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 77
Connection: keep-alive

{"links":[{"rel":"projects","href":"https://api.errorception.com/projects"}]}

Most API calls require authentication. The API currently only supports HTTP Basic Auth. Use your email address as the username and your account password as the password.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format, ie: YYYY-MM-DDTHH:MM:SS.MSZ

HTTP Redirects

API calls may return HTTP redirects. Clients should follow such redirects if they encounter them. The location that the client should redirect to will be found in the Location header. The status code for redirection would be either 301 or 302. Note that a redirect is not an error.

Navigation

All clients should should start from the root, ie. https://api.errorception.com/. Other than this URL, the client shouldn't hard-code any other URL. This will ensure that the client is safe-guarded in the event that URLs change in the future.

In most JSON objects, the server will include a links array. This will contain the list of URLs that are relevent to the object. The client is expected to pick one from this list.

{
    ...
    "links":[
        {"rel":"open-errors", "href":"https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors"},
        {"rel":"ignored-errors", "href":"https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?status=ignored"},
        {"rel":"closed-errors", "href":"https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?status=closed"}
    ],
    ...
}

The client should use the rel property to decide which URL to pick.

HTTP Status Codes

Every response will have a HTTP status code that will rather accurately describe the result of the operation. Clients should use this to determine whether the call was a success or a failure, and how to proceed in case of failures.

Status Code What it means
200 Success!
304 Not Modified. There's no new data to return
400 Bad Request. There was something wrong with the request. An descriptive message in the response will tell you what exactly went wrong.
401 Unauthorized. Your email/password was either not provided or was incorrect. Errorception currently only supports HTTP Basic Authentication.
404 Not Found. The resource you requested doesn't exist.
420 Chill Winston. You have hit the rate-limit. The server imposes a limit of 5000 requests/hour. If you exceed that limit, you will get this response for the rest of the hour.
500 Internal Server Error. The server messed up, and doesn't know what it did wrong. If you were expecting a good response, let me know, and I'll fix it asap.

Pagination

Some responses, typically lists, may be paginated. Clients should look at the Link header to determine how to paginate the response.

$ curl -i -u "[email protected]" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?page=2
Enter host password for user '[email protected]':
HTTP/1.1 200 OK
X-RateLimit-Remaining: 4998
Cache-Control: max-age=0, private, must-revalidate
X-Media-Type: application/vnd.errorception.v1+json
Link: <https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors>; rel="prev", <https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?page=3>; rel="next"
Content-Type: application/json; charset=utf-8
Content-Length: 13739
Connection: keep-alive

...

The link tag contains a comma separated list of link/rel pairs that will help you paginate the response. Possible values for rel are prev and next.

If you want to control how pagination works, you can optionally provide the following querystring parameter:

Parameter Default What it does
pagesize 20

Controls how many items you want to fetch in one page.
Example: ?pagesize=50.
Only integers are allowed. A value smaller than 1 will throw a BadRequest error. A value larger than 100 will be set to 100.

Future proofing the client

To ensure that the client code doesn't break when the API version changes, it is strongly recommended that clients send the appropriate Accept header. Since the API is at version 1 right now, you should send Accept: application/vnd.errorception.v1+json.

Note that while this header is optional, it's highly recommended that you set it. If this header isn't provided, or is a value that isn't understood by the server, the server will assume that the request was for the latest version of the API. This might not be what the client expects, and might break the client.

Root resource: GET /

Returns a list of top-level resources you can access. Currently, this only contains the rel="projects" resource.

Getting your projects list

To get your list of projects, GET the rel="projects" resource you obtained from GET /.

$ curl -i -u "[email protected]" https://api.errorception.com/projects
Enter host password for user '[email protected]':
HTTP/1.1 200 OK
X-RateLimit-Remaining: 4996
Cache-Control: max-age=0, private, must-revalidate
X-Media-Type: application/vnd.errorception.v1+json
Content-Type: application/json; charset=utf-8
Content-Length: 1721
Connection: keep-alive

Sample response:

[
    {
        "name": "blog.rakeshpai.me",
        "occurrenceStats": {
            "dt20121112":2,
            "dt20121111":4,
            "dt20121110":4,
            "dt20121109":9,
            "dt20121108":7,
            "dt20121107":20,
            "dt20121106":13,
            "dt20121105":5,
            "dt20121104":11,
            "dt20121103":14,
            "dt20121102":13,
            "dt20121101":14,
            "dt20121031":11,
            "dt20121030":6,
            "dt20121029":38,
            "dt20121028":4,
            "dt20121027":3
        },
        "plan": "free",
        "rateLimit": 100,
        "createDate": "2011-08-17T01:16:02.002Z",
        "links": [
            {
                "rel": "open-errors",
                "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors"
            },
            {
                "rel": "ignored-errors",
                "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?status=ignored"
            },
            {
                "rel":"closed-errors",
                "href":"https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?status=closed"
            }
        ]
    },
    ....
]

Some explaination of the response:

Getting a list of errors

Use either of the links as described by the rel attributes from the example above to get the appropriate list of errors.

$ curl -i -u "[email protected]" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors
Enter host password for user '[email protected]':
HTTP/1.1 200 OK
X-RateLimit-Remaining: 4998
Cache-Control: max-age=0, private, must-revalidate
X-Media-Type: application/vnd.errorception.v1+json
Link: <https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?page=2>; rel="next"
Content-Type: application/json; charset=utf-8
Content-Length: 13739
Connection: keep-alive

...

Sample response:

[
    {
        "isInline": true,
        "message": "\"_WidgetManager\" is undefined",
        "numPages": 15,
        "browsers": ["Internet Explorer 8", "Internet Explorer 7", "Internet Explorer 6", "Internet Explorer 9"],
        "mostRecentDate": "2012-11-12T15:31:02.576Z",
        "occurrenceCount": 915,
        "when": "before",
        "occurrencesThisWeek": [0, 0, 0, 0, 0, 0, 0],
        "examplePage": "http://blog.rakeshpai.me/2007/02/ies-unknown-runtime-error-when-using.html",
        "line": 3049,
        "status": "open",
        "links": [
            {
                "rel": "details",
                "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc"
            },
            {
                "rel": "occurrences",
                "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc/occurrences"
            }
        ],
        "scriptPath": null
    },
    ...
]

Some things to note:

To sort and/or filter the errors list, you can provide the following query-string parameters:

Parameter Default What it means
from (the beginning) Sets the time from when you want to get the errors. This could either mean the time when the first occurred, or could mean when the error most recently occurred, and is controlled by the new parameter described below.
to (just now) Sets the time till when you want to get the errors. Like from above, the semantics of what it means is defined by new.
browser (all) Narrows the listing down to only certain browsers. If left blank, it fetches the listing for all browsers. Possible values are firefox (Gecko browsers), webkit, ie, opera and others.
new false If true, returns only errors that occurred for the first time between from and to dates. If false, returns errors that might even have recurred in the time range.
sortby recency Possible values are frequency and recency. If recency is specified, the results are sorted by their mostRecentDate. Or else, they are sorted by their occurrenceCount.
order desc Determines how the listing should be sorted. Could either be asc or desc.

Getting error details

Every error object returned has a link to it's details.

$ curl -i -u "[email protected]" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc
Enter host password for user '[email protected]':
HTTP/1.1 200 OK
X-RateLimit-Remaining: 4997
Cache-Control: max-age=0, private, must-revalidate
X-Media-Type: application/vnd.errorception.v1+json
Content-Type: application/json; charset=utf-8
Content-Length: 798
Connection: keep-alive

...

Sample response:


{
    "isInline": true,
    "message": "\"_WidgetManager\" is undefined",
    "browsers": ["Internet Explorer 6", "Internet Explorer 7", "Internet Explorer 8", "Internet Explorer 9"],
    "mostRecentDate": "2012-11-12T15:31:02.576Z",
    "occurrenceCount": 915,
    "when": "before",
    "line": 3049,
    "status": "open",
    "links": [{
        "rel": "details",
        "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc"
    }, {
        "rel": "occurrences",
        "href": "https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc/occurrences"
    }],
    "scriptPath": null,
    "occurrencesByBrowser": {
        "Internet Explorer 9": 30,
        "Internet Explorer 8": 549,
        "Internet Explorer 7": 259,
        "Internet Explorer 6": 77
    },
    "statusHistory": [{
        "userId": "system",
        "email": "Errorception",
        "date": "2011-08-17T04:53:00.374Z",
        "status": "open"
    }]
}

The response to this call is similar to that of the listing of errors, except there are two new keys. occurrencesByBrowser gives a browser-wise split of the occurrence counts. statusHistory gives the history of status changes to this error.

In the statusHistory list, if the userId is system, the email will be the invalid email Errorception. Otherwise, the email field will be the email address of the user in your project who changed the status.

The statusHistory list is sorted in reverse-chronological order.

Getting the list of occurrences of an error

The error object also contains a occurrences link that you can use to get the list of its occurrences.

$ curl -i -u "[email protected]" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc/occurrences
Enter host password for user '[email protected]':
HTTP/1.1 200 OK
X-RateLimit-Remaining: 4995
Cache-Control: max-age=0, private, must-revalidate
X-Media-Type: application/vnd.errorception.v1+json
Content-Type: application/json; charset=utf-8
Content-Length: 2
Connection: keep-alive

...

Sample response:

[
    {
        "line": 2049,
        "page": "http://blog.rakeshpai.me/2007/02/ies-unknown-runtime-error-when-using.html",
        "isInline": true,
        "scriptPath": null,
        "useragent": "Mozilla/5.0 (iPad; CPU OS 6_0_1 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A523 Safari/8536.25",
        "when": "before",
        "date": "2012-11-12T15:31:02.576Z",
        "meta": null
    }
]

This is a paginated response, clients should check the Link header to determine how to navigate the response.

Most keys are the usual, and have been described before. useragent is the full UserAgent string of the browser. meta is either null, or an object containing custom key-value pairs. The values of the meta can be specified at the time the error is posted. Read the client side docs to know how this is done.

Rate limits

There's a hard limit of 5000 requests per user per hour for the API. This limit resets at the turn of the hour every hour. The remaining number of requests you can make is returned in the responses for all rate-limited requests, and is contained in the X-RateLimit-Remaining header.

There's currently no way to bypass the rate-limit. Workarounds are planned though. Watch this space for more.