HTTP API

Do what you like with your errors

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 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.

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 "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.

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.

$ 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"}]}

Getting your projects list

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.

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 "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:

  • 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 descending 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 "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.

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 "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.