Errors & Status Codes

Tilia uses standard HTTP status codes to indicate the success or failure of your API requests. If a request fails, our endpoints return an error using the appropriate status code.

In general, there are three status code ranges you can expect:

  • 2xx success status codes indicate the request worked as expected
  • 4xx error status codes indicate an error due to the information provided (e.g., an invalid resource was requested)
  • 5xx error status codes indicate an error with Tilia’s servers (these are rare)
Status Code Description
200 - OK Success. Everything worked as expected.
201 - OK A new resource was created and is present in the response body.
400 - Bad Request The request was unacceptable, often due to invalid or missing parameter(s).
401 - Unauthorized Unauthorized client or scope in the request. Missing or incorrect authentication credentials.
403 - Forbidden The request is understood, but it has been refused or access is not allowed.
404 - Not found The URI is invalid or the requested resource does not exist.
405 - Method Not Allowed The request attempted to access a resource using an unsupported HTTP method.
500 - Internal Server Error A problem occurred on Tilia's servers.

Error Response

In addition to the HTTP status code, most of our endpoints return additional information describing the errors.

  • status : The status of the request. Typically returns Success or Failure .
  • message : A descriptive string providing further details about the error.
  • codes : The error code returned by the request.
  • payload : When available, additional detail about the error is provided in the response payload.

The exact error response varies depending on the endpoint being called and the error conditions. The following shows an error response when the request body contains malformed JSON.

Copy
Copied
{
    "status": "Failure",
    "message": [
        "input is invalid"
    ],
    "codes": [
        "INPUT_ERROR"
    ],
    "payload": {
        "errors": {
            "request_format": [
                "INVALID_VALUE"
            ]
        }
    }
}

The following shows an error response when trying to register a user using a username that is already registered.

Copy
Copied
{
    "status": "Failure",
    "message": [
        "failed to validate input"
    ],
    "codes": [
        "VALIDATION_ERROR"
    ],
    "payload": {
        "errors": {
            "username": "USERNAME_ALREADY_TAKEN"
        }
    }
}