Every API response contains two fields:
These fields may not be populated but upon returning an error the API will also give more information about an error with these two fields. They are described in more detail below.
ResponseStatus
This field gives detailed information about the error, if any, that occurred. If the API call did not have an error, and a success HTTP result code of 200 response is returned, the ResponseStatus would be empty. If any other code is received, ResponseStatus may be populated with a human-readable message.
Notifications
Notifications are included with every API response. This field may be populated with information about planned system downtime and in some cases with error details.
400 BadRequests may occur in a few cases during the authorization steps. If a user has not given access or has denied access the response would be a 400. These responses are seen in Obtaining Access Tokens. They are described below.
Response with the user not yet finishing the access grant:
HTTP/1.1 400 BadRequest
Content-Type: application/json
Date: Thu, 28 Jun 2012 15:22:59 GMT
Content-Length: 115
{
"error":"authorization_pending",
"error_description":"User has not yet approved the access request"
}
Response with the user rejecting the access grant:
HTTP/1.1 400 BadRequest
Content-Type: application/json
Date: Thu, 28 Jun 2012 15:22:59 GMT
Content-Length: 115
{
"error":"access_denied",
"error_description":"User has denied the access request"
}
A 403 forbidden is generally thrown when the application or user calling the API did not have sufficient BROWSE, READ, or WRITE permission to the resource that is being called.
For example, the 403 Forbidden response is returned when attempting to access a project with id 13013 that the current user does not have access to:
GET https://api.basespace.illumina.com/v1pre3/projects/13013
{
"ResponseStatus": {
"ErrorCode": "Forbidden",
"Message": "Sorry but this requires BROWSE access to this Project resource."
},
"Notifications": [
{
"Type": "error",
"Item": "Sorry but this requires BROWSE access to this Project resource."
}
]
}
Or, for example, the following is a response for fetching information about another user:
{
"ResponseStatus": {
"ErrorCode": "Forbidden",
"Message": "Forbidden",
"Errors": []
}
}
A 404 Not Found is generally returned when the resource being requested does not exist. This response is common when something is mis-spelled or the resource or file does not exist.
For example, a 404 Not Found is returned when trying to access project id 1121 which does not exist:
GET https://api.basespace.illumina.com/v1pre3/projects/1121
{
"ResponseStatus": {
"ErrorCode": "NotFound",
"Message": "Project id '1121' doesn't exist"
},
"Notifications": [
{
"Type": "error",
"Item": "Project id '1121' doesn't exist"
}
]
}