HTTP status codes

The Brightpearl API is an example of a set of RESTful web services. One of the principles of  RESTful web services  is that they should embrace and make use of the conventions and functionality provided by HTTP, rather than just ignorning it as SOAP web-services tend to do.

The most obvious illustrations of this is how  HTTP status codes  are used; generally speaking requests to a SOAP API will always result in a response with the HTTP code 200 OK, even if the response wasn't completed as expected. To understand the acutal outcome of the request, the receipient of the SOAP response will need parse the XML response and inspect its contents. By contrast, RESTful APIs tend to make use of many different HTTP status codes to provide 'at a glance' indications of the result of a request, and this is the approach we have used with the Brightpearl API.

The design of the Brightpearl API has been heavily influenced by the book  RESTful web services  by Leonard Richardson and Sam Ruby. Wherever possible we have used the definitions of the various status codes introduced in the appendices of that book.

Informational 1xx

Not explicitly used

Successful 2xx

200 OK The request was as completed as expected: if you issued a GET, one or more resources were returned; POST, one or more resources were created; PUT one or more resources were modified; DELETE one or more resources were destroyed.
207 Multi-Status Only returned if you have performed a destructive operation (POST, PUT, DELETE) against more than one resource and the operations against each indiviudal resource did not share a common outcome. For example, if you DELETEd two resources and both were deleted you can expect 200. If both DELETEs were forbidden, you'd expect 403. If one DELETE was successful but one was forbidden, you would receive 207. Information about the result of each individual operation is included in the response

Redirection 3xx

Not explicitly used, but you should configure your HTTP connection library to accept and follow 301 and 302 in case we ever need to modify a URI without notice or if a network proxy exists between your device and the Brightpearl servers.

Client Error 4xx

400 Bad Request You will generally encounter this status code if you send a malformed request to the Brightpearl API or if that request cannot be validated. For example if you attempt to create a contact with a missing or invalid email addres, you can expect to receive a 400.
401 Unauthorized If you attempt to access the Brightpearl API without an authorisation token, or attempt to authorise yourself using invalid credentials, you will receive 401
403 Forbidden For reasons of security, the reasons why you receive this status code are kept vague, but you will receive it when you attempt to do something the Brightpearl API decides that you are not allowed to.
404 Not Found 404 means that the resource you wanted to manipulate could not be found; for example issuing a  Warehouse DELETE  against anDOn ID  that does not exist will result in a404. It can also mean that you have a mistake in the structure of your URI, so when you are first developing your integration, check your URIs when you see a 404.
409 Conflict We will send this error if your request is syntactically correct but violates some business rule. For example, if you issue a  Warehouse POST  request which is syntactically correct but specifies a warehouse name that is already in use, you will receive a 409

400 vs 409

The difference between 400 and 409 is subtle, and for the most part users of the Brightpearl API do not need to treat them differently. There are some cases where a request could be considered a 400 (in some way invalid) and 409 (violating some business rules). In this case you will receive a 400.

Server-Side Error 5xx

500 Internal Server Error This status code indicates a technical failure inside the Brightpearl API. You can infer nothing about the actual status of your response from this status code, and you should proceed with caution before attempting to issue the request again. If you receive this status code, the body of the response should include instructions on how to contact Brightpearl.
503 Service Unavailable You will receive this status code if the Brightpearl API is too busy to accept your request, or if your access to the Brightpearl API has been temporarily suspended due to overuse.
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.