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:

occurrenceStats gives the number of errors caught over the last 15 days. The keys in this object are in the dtYYYYMMDD format.
links contains the addresses of the listing of errors. open-errors, ignored-errors and closed-errors are possible values.

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:

If isInline is true, scriptPath will always be null.
numPages is the total number of pages that this error has occurred on.
occurrenceCount is the total number of times the error has occurred.
occurrencesThisWeek is the list of occurrences over the last 7 days including today, sorted in decending order of the date.
examplePage is a randomly picked page on which the error occurred.
While line is provided irrespective of whether the error isInline or not, it only really makes sense when the error is not inline. It should be considered an indicative value if isInline: true. When the error is an inline error, you will be able to get per-occurrence line numbers by querying for the error's occurrences list.
when describes whether the error occurred before page load, or after page load.
status describes if the error is open, closed, ignored or reopened. Fetching open errors will also fetch reopened errors. closed and ignored have different end-points.
The links attribute will allow you to get at details about each error, or a list of its occurrences.
This is a paginated response. You should check the Link header to get more results.

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.

Painless JavaScript Error Tracking

Contents

Errorception HTTP API

Outline

HTTP Redirects

Navigation

HTTP Status Codes

Pagination

Future proofing the client

Root resource: `GET /`

Getting your projects list

Getting a list of errors

Getting error details

Getting the list of occurrences of an error

Rate limits

Painless JavaScript Error Tracking

Contents

Errorception HTTP API

Outline

HTTP Redirects

Navigation

HTTP Status Codes

Pagination

Future proofing the client

Root resource: GET /

Getting your projects list

Getting a list of errors

Getting error details

Getting the list of occurrences of an error

Rate limits

Root resource: `GET /`