Do what you like with your errors
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
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.
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 relevant 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.
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. |
Some responses, typically lists, may be paginated. Clients should look at the Link
header to determine how to paginate the response.
$ curl -i -u "rakeshpai@errorception.com" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors?page=2
Enter host password for user 'rakeshpai@errorception.com':
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 header 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.
|
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.
GET /
Returns a list of top-level resources you can access. Currently, this only contains the rel="projects"
resource.
$ 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"}]}
To get your list of projects, GET
the rel="projects"
resource you obtained from GET /
above.
$ curl -i -u "rakeshpai@errorception.com" https://api.errorception.com/projects
Enter host password for user 'rakeshpai@errorception.com':
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 explanation 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.
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 "rakeshpai@errorception.com" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors
Enter host password for user 'rakeshpai@errorception.com':
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:
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 descending order of the date.examplePage
is a randomly picked page on which the error occurred.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.links
attribute will allow you to get at details
about each error, or a list of its occurrences
.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 . |
Every error object returned has a link
to it's details
.
$ curl -i -u "rakeshpai@errorception.com" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc
Enter host password for user 'rakeshpai@errorception.com':
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.
The error object also contains a occurrences
link
that you can use to get the list of its occurrences.
$ curl -i -u "rakeshpai@errorception.com" https://api.errorception.com/projects/4e4b1652f384ef4d2d000002/errors/4ecc86a0fc68e61a1a06fdfc/occurrences
Enter host password for user 'rakeshpai@errorception.com':
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.