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)

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.

{
    "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.

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