HTTP Verbs and Error Codes (legacy)

HTTP Verbs

Where possible, our API strives to use appropriate HTTP verbs for each action.

Verb	Description
`GET`	Retrieving resources.
`POST`	Creating new resources or other types of content submission.
`PUT`	Updating resources. Note: some types of resources cannot be updated.
`DELETE`	Deleting resources. A successful delete will return a `200` or `204` response, even if no payload is attached.

Success Codes

If your request has been successful, you will receive one of the following status codes:

200 OK
Success (e.g., resource updated or retrieved, etc.). Note: a body is not always returned.
201 Created
A new resource has been successfully created (a Thng, collection, etc.). The Location header will contain the URL of the resource. The response payload will contain the resource created in the body.
202 Accepted
The request was accepted successfully, and will be fulfilled asynchronously. In most cases, the resource can be polled for completion status.
204 No Content
The request was successful, and there are no results to return. An example of this is a DELETE operation.

Error Codes

When calling our API you might get sometimes an error code, which you must handle within your application. Errors can happen because your request to our API didn't follow our specifications, or because our services are facing a temporary problem.

400 Bad Request
If you send an incorrect JSON document (e.g. a "}" is missing), or if the syntax/content is incorrect.
401 Unauthorized
The access credentials (via the Authorization header) were missing or are invalid.
403 Forbidden
The credentials you provided are valid, but you are not authorized to access the resource you were looking for.
404 Not found
Returned when the request is valid, but the resource you try to access does not exist, or is outside your scope.
405 Method Not Allowed
The verb/method you used to fulfill the request is not supported for this resource.
415 Unsupported Media Type
Returned when the the format you requested (e.g., XML) is not supported for this resource. Note: we only support application/json as valid content type.
500 Internal Server Error
An error on our side, we're sorry. Hopefully, you will never see one, but if you do please get in touch including details of the request you tried and the response you received.
503 Service Unavailable
Most likely when an external service needed to fulfil your request did not reply.
504 Gateway Timeout
A service required to fulfill the request was not available.

Error Messages

Errors will return a JSON payload with one or more error messages to help you understand what went wrong. Below is an example of such an error response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": 401,
  "errors": [
    "Access denied, please check your credentials!"
  ],
  "code": 33619968,
  "moreInfo": "https://developers.evrythng.com/docs/authentication"
}

All error objects have status and errors properties so your HTTP client can handle the problem appropriately. There may also be a code field to let you know what is wrong with the request.

These are some of the the possible error codes:

Error Code	Description
`INVALID_ID`	The formatting of a resource identifier is incorrect.
`INVALID_CONTENT`	A required field or parameter for the resource has not been set.
`INVALID_STATE`	The state of a resource does not allow to fulfill a request.
`MISSING_RESOURCE`	A resource does not exist.
`ALREADY_EXISTS`	Another resource has the same value for this field, which can happen when the field is used as unique key (for example the email address of a user).
`ACCESS_FORBIDDEN`	A resource does not allow access with the provided credentials.
`METHOD_FORBIDDEN`	A resource does not allow to use the verb with the provided credentials, for example it can happen when the user has limited permissions only to read a content (`GET`).