LUSID uses HTTP status codes to describe responses from the API. In this article you will learn how to use them.
The LUSID API follows the REST style architecture which includes using HTTP response codes to return the status of requests.
LUSID entities that form part of the data model are modelled as resources on the API and use HTTP verbs for performing operations on them. The basic operations are described below:
GET requests are used to retrieve resources that already exist in LUSID e.g. getting a portfolio. A successful request will return a response with a HTTP status code of 200.
POST requests are used to create or upsert resources in LUSID e.g. create a portfolio. A successful request will return a response with a HTTP status code of 201.
POST requests are also to execute functions on the API e.g. aggregation. A successful request will return a response with a HTTP status code of 200.
PUT requests are used to update resources that already exist in LUSID. A PUT request will only update the fields specified as part of the request, any optional fields that are not specified will be removed as part of the update. This means that if you intend to update a single field you must ensure that you also supply all the fields you re not updating as part of the request. A successful request will return a response with a HTTP status code of 200.
DELETE requests are used to delete resources that already exist in LUSID e.g. delete a portfolio A successful request will return a response with a HTTP status code of 200.
LUSID uses HTTP response codes to indicate the status of requests, below is a summary of the most common status codes returned by LUSID when requests fail.
400 - Bad Request
Returned when the request contains invalid data, incorrectly formatted data or missing fields.
401 - Unauthorised
The request does not contain a valid Open Id Connect token. If this is encountered you may need to reauthenticate with Okta.
403 - Forbidden
You do not have access to the requested resource, you may not have the required permissions to complete the request and you should consult your entitlements manager for LUSID.
404 - Not Found
The requested resource does not exists
Responses using the LUSID SDK
Unsuccessful calls to the LUSID API will throw an ApiException which will contain the HTTP status code and an ErrorResponse. The ErrorResponse will contain:
- status - The HTTP status code
- code - LUSID code indicating the type of error, for more details see https://docs.lusid.com/#section/Error-Codes
- message - Summary of the error
- detailedMessage - Detailed description of the error
- items - If the request contained multiple resources, the items will list each of the items that failed along with the details of why