HTTP Verbs and Error Codes (legacy)

HTTP Verbs

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

GETRetrieving resources.
POSTCreating new resources or other types of content submission.
PUTUpdating resources. Note: some types of resources cannot be updated.
DELETEDeleting 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": ""

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 CodeDescription
INVALID_IDThe formatting of a resource identifier is incorrect.
INVALID_CONTENTA required field or parameter for the resource has not been set.
INVALID_STATEThe state of a resource does not allow to fulfill a request.
MISSING_RESOURCEA resource does not exist.
ALREADY_EXISTSAnother 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_FORBIDDENA resource does not allow access with the provided credentials.
METHOD_FORBIDDENA 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).