Droplit.io Portal
API Reference

Standard Responses

Overview

The Droplit REST API uses a variety of standard JSON responses and HTTP status codes in specific contexts. These responses and status codes are described in detail below.

Each status code documented in a REST endpoint links back to its details on this page. The REST endpoint pages themselves highlight the specific context in which that status code appears, rather than repeating the standard structures. Any deviation from the standard structures is described in depth on the relevant endpoint page.

If any other status codes or unusual structures are returned from an endpoint, which are not documented here, or a JSON response is given that is not documented in a specific endpoint, please contact Droplit to report it.

200 (Success)

Most endpoints return a 200 status when they have been executed correctly. This status always contains a JSON object if a payload is requested, and often contains JSON objects in other contexts. However, it may not always contain a JSON object.

201 (Created)

Endpoints that successfully create a new resource return a 201 status. This status sometimes includes a JSON object documenting the object that was created, but does not always.

400 (Bad Request)

An endpoint returns a 400 status when its request is malformed. This is usually returned when the validation of parameters fails, but can also be returned in other contexts. The full response includes a JSON object which contains details on what is malformed in the request.

The individual API endpoints do not list every possible JSON object that may be generated from a bad request. Instead, they list the type of bad request, with a summary of what is found in the error object. This summary, along with the error object, should clarify any error caused by a usage mistake.

An error response such as the following, for example, would be listed as "No Query String Allowed" or "Query Field Not Allowed," depending on the needs of a particular endpoint. In order:

  1. The error happened because of invalid parameters.
  2. The error was in the query string.
  3. One or more values specified in the query string were not allowed as parameters. 
{
	"errorType": "InvalidParams",
	"errors": [
		{
			"in": "query",
			"message": "contains fields that are not allowed: [ ADDITIONAL-FIELD-NAMES ]",
			"path": "additional parameters"
		}
	]
}

401 (Unauthorized)

An endpoint returns a 401 status when authentication has failed, an incorrect token type has been given for an endpoint, or authentication is required and has not been provided. The status means that the system cannot identify the user as authentic, for security reasons.

403 (Forbidden)

An endpoint returns a 403 status when the user is authenticated, but is not authorized to run the endpoint. This can happen in the following ways:

  • The user has a valid token, but that token type is invalid for the endpoint in question.
  • The user is trying to access a resource through a container which doesn't encapsulate that resource.

404 (Not Found)

An endpoint returns a 404 status when the resource it is trying to access does not exist. The request is semantically correct, but refers to a non-existent record in the system.

405 (Method Not Allowed)

An endpoint returns a 405 status when a user attempts to use an HTTP verb that is not supported. The OPTIONS verb is supported on all endpoints, as described in the REST API usage techniques, and shows which HTTP verbs a particular endpoint supports.

500 (Internal Server Error)

An endpoint returns a 500 status when something has gone wrong on the Droplit server side. There are instances in which this is to be expected, when the server runs into an operation it cannot complete. If this error occurs in a call that was anticipated to run properly, however, please contact Droplit to report it.

503 (Service Unavailable)

An endpoint returns a 503 status when something on the Droplit server is not currently available, usually for maintenance or similar purposes. The service should be restored in short order without any action from the user. Please contact Droplit if a service is down for more than 24 hours.