Return values

For each request there will be an HTTP protocol return value (see RFC 2616). This way the user will know if its request has been successful or not.

Additionally, for each request there might be a JSON object (responses with a 204 return code will not have any data) which might have the following fields:

  • errors: List of errors or warnings occurred during request’s execution. A request might be successful and still have errors (warnings). If no error happened, this key won’t exist.
  • msg: List of additional information not covered in either the resource or the error list. This key won’t exist if there is none.
  • queue_token: If the request is queued, this key will contain information for querying the status of a queued request.
  • <resource>: Information/Resource asked for. Its name will depend upon the request. i.e.: create disk will return a disk key.

Success Codes

Possible return codes meaning a successful request
Code Explanation
200 Request successful and there will be a JSON object
201 Resource created. There will be a JSON object
204 Request successful, but won’t return anything.
202 Request successfully queued, there will be a token for querying about the queued request progress, there will be also a JSON object with known data, although queued request might still fail.

Error Codes

Explanation of error codes used

Possible errors returned
Code Explanation
400 Bad Request: Malformed syntax or a bad query. Route doesn’t exist or JSON parameters aren’t valid.
401 Unauthorized: Action requires user authentication
403 Forbidden: Authentication failure or invalid Application ID
404 Not Found: Resource not found
405 Not Allowed: Method not allowed on resource. Route does exist but it is not using the correct HTTP method (POST instead of GET, etc.)
406 Not Acceptable: Requested representation not available for the resource. In our case, header must ask for an application/json, as this is currently the only option supported.
409 Resource Conflict (PUT, PUT, DELETE): State of the resource doesn’t permit request. I.e.: disk is blocked.
412 Precondition failed (GET): Operation not completed because preconditions were not met. This will only happen if a resource depends on other and the latter is not in an acceptable state. i.e.: Deleting a vm with its disks blocked.
416 Requested Range Not Satisfiable (GET): Requested range not satisfiable. Wrong pagination request
417 Application error
500 Server Error (GET, POST, PUT): Internal server error
501 Not Implemented (POST, PUT, DELETE): Requested HTTP operation not yet implemented.
502 Bad Gateway: Backend service failure (data store failure). Api is not available.
503 Service Unavailable: Down for maintenance

Error codes classified by type of Request

Possible error codes by type of api call
Api call type Possible error codes
Any 401, 403, 406, 500, 501, 502, 503
Unknown 400, 405
Create 400, 412
Delete 404, 409, 412
Edit 400, 404, 409, 412
Do Action (POST) 400, 404, 409, 412
Get by id 404, 416
List (GET) 400, 404, 416

Table Of Contents

Previous topic

Pagination

Next topic

Load balancing