Status codes and errors
BeBanjo APIs return appropriate HTTP status codes for every request. Additionally, in some error requests, the body of the response might contain a message explaining the problem. But it is the status code and not the body what you should use to know whether a request was successful or not.
2xx AKA success!
BeBanjo APIs will return a 2xx status code for any type of requests (
DELETE) that is received, understood, accepted and processed successfully. So, you should consider any request returning a 2xx status code to be successful.
Even though BeBanjo APIs will return one of the different 2xx status codes depending on the action performed (see the examples below), you are advised not to couple your code to one of the specific types. Any 2xx code should be considered a successful request.
Common status codes:
200 OK: This is the standard response for successful requests. BeBanjo API’s will normally return this for successful
201 Created: The request has been fulfilled and resulted in a new resource being created. BeBanjo API’s will normally return this for successful
202 Accepted: The request has been accepted for processing, but the processing has not been completed. In some cases, BeBanjo API’s will need to do the requested processing in the background, in those cases (which are noted in the documentation) a 202 code will be returned.
204 No Content: The server successfully processed the request, but is not returning any content. BeBanjo API’s will normally return this for successful
4xx AKA the request failed and it’s probably your fault
The 4xx status code will be returned when the request cannot be processed because something is wrong in the request you’re sending. Maybe you didn’t authenticate properly, you’re trying to access to a non-existing resource or you’re trying to create a resource without providing all the required data. The body of the response will normally explain what’s the reason for the request being rejected.
You’ll normally get these errors when developing your integration and testing our APIs. However, in production, if you use our APIs properly, these errors shouldn’t happen. If they do, there’s probably something wrong in the way you’re trying to use BeBanjo API’s. Find below some advice on how to deal with errors.
Common status codes:
400 Bad Request: The request cannot be fulfilled due to bad syntax. Maybe the body of your request is not valid XML.
401 Authorization Required: The credentials used in the request are missing or invalid. Maybe you’re not using digest authentication properly or your credentials are wrong.
404 Not Found: The resource can’t be found. The URL you’re using is wrong for some reason. Maybe you’ve got an old link of a resource that no longer exists.
405 Method Not Allowed: the HTTP method is not appropriate. Not every resource support the four operations (
DELETE), if you send a request to a resource that doesn’t support the operation you’re requesting, you’ll get a 405.
406 Not Acceptable: the Accept header that you sent (
GETrequests) is not supported. Make sure that your requests include a supported Accept header.
415 Unsupported Media Type: the Content-Type header that you sent (
PUTrequests) is not supported. Make sure that your requests include a supported
422 Unprocessable Entity: the resource submitted in the request can’t be processed. You might be sending invalid attribute values or validation errors. Check the body of the response for more details.
5xx AKA the request failed and it’s probably our fault
Note: When the Movida and Sequence applications are in maintenance mode then their APIs will return a 503 status code.
The 5xx status codes will be returned when your request is apparently valid, but some problem in the server prevented the request from being processed. Maybe some part of our infrastructure is temporarily down, there’s a bug or there are connectivity issues.
These errors are infrequent but they can happen and you should be prepared to deal with them. BeBanjo’s Support team is immediately notified of each occurrence of any of these errors so that they can take action as soon as possible.
Dealing with errors
Since the requests that you send can fail, your production code should be prepared to handle error scenarios gracefully.
Any operation in BeBanjo APIs is atomic, meaning that each request is either completely processed or not processed at all. In any case, the system always stays in a consistent state. When one of our APIs returns a 4xx or a 5xx error, you can safely assume that nothing has been changed in the system.
If your integration processing includes several operations that need to be requested sequentially, and one of those operations returns an error, in general, you should not continue that processing. We also advise you to setup a logging and/or notification mechanism that will alert you when this happens so you can take action on it.
When debugging a 4xx error, as explained in the section above, you should check the specific status code along with the body of the response to understand what was wrong with the request that you sent. Looking at the documentation page for the specific resource and operation you’re performing can also help you debugging the error. Finally, if you don’t find the reason for the error, you can always get in touch with the BeBanjo Support team at firstname.lastname@example.org.
If what you’ve got is a 5xx error, even though the BeBanjo Support team will be automatically notified of it, you should also get in touch at email@example.com. The more information you can provide about the failing request (e.g. URL, type of operation, body, time of the request…) the easier will be for us to help you with the problem.
Some 5xx errors might be returned for transitory circumstances (high load in our servers, connectivity issues, etc.). In order to make your integration code more robust, you may want to implement a retry mechanism. Basically, your code could automatically retry any 5xx failing request a few times before giving up and notifying you.
We kindly ask you to be reasonable when retrying. There’s no point in sending a huge amount of retries in a short period of time. We suggest to wait a few seconds between each retry.
One sensible approach would be to follow an exponential delay logic. For example, your code could perform a 1st retry 2 seconds after the first attempt, then a 2nd retry 4 seconds after, then a 3rd retry 16 seconds after and so on. With something like this, four retries should probably be enough. If after all the retries, you keep getting a 5xx error, then your code should give up, stop the processing and notify you.
Please note that you shouldn’t retry 4xx errors. Those are caused because something is wrong with the request, meaning that any retry will always fail again. So, if you decide to implement a retry mechanism, please make sure to only do it for 5xx errors.
Last updated October 10th, 2017.