Handling errors

Whenever you send a request to the Bitrush API you'll get a response in JSON (JavaScript Object Notation) format. This is a standard for data communication that's easy to read for humans as well as machines. Alongside the JSON-response an HTTP status code is sent that shows whether the request was successful or not. If it wasn't, you can tell by the code and the message in the JSON-response what went wrong.

Succesful request

An HTTP status 200 OK is issued whenever your request was a success. You see this type of response in our examples like this one below where we successfully retrieve the current API version.

curl -i https://api.bitrush.nl/info
application/json; charset=utf-8
    "version": 1

Failed request

Things will sometimes go wrong. For instance when a product identifier doesn't exist, this error will be the result:

curl -i https://api.bitrush.nl/v1/products/XXX-XXX
application/json; charset=utf-8
    "error": {
        "message": "Product not found."

HTTP status code

The first digit of the status code indicates the type or class of the status. Using this first digit you can determine the best approach for dealing with an error. The following classes of codes are relevant to the Bitrush API:

  • A code in the 2xx range comes with a Bitrush API response indicating success.
  • A code in the 4xx range is an error code returned from the Bitrush API where the client (your responsibility) seems to be causing the error. Whenever this happens you can change your code to prevent the error from happening again. The error for this specific request usually won't go away by itself.
  • A code in the 5xx range is an error caused by the server (Bitrush's responsibility). So caused by the Bitrush API or it's infrastructure. In the rare case you get this type of error, something is wrong with the Bitrush API. The errors should subside without your mediation.

All possible status codes

The Bitrush API will only ever return a subset of all legal HTTP status codes. Here's the full list:

OK - Everything worked as expected.
Bad Request - The request was unacceptable, often due to missing a required parameter.
Request Failed - The parameters were valid but the request failed.
Not Found - The requested resource doesn't exist.
Too Many Requests - Too many requests hit the API too quickly.
500 502 503 504
Server Errors - Something went wrong on Bitrush's end. (These are rare.)