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:
2xxsuccess status codes indicate the request worked as expected4xxerror status codes indicate an error due to the information provided (e.g., an invalid resource was requested)5xxerror status codes indicate Tilia could not complete the request, for a reason on Tilia’s side rather than in your request (these are rare). A503is temporary. When it comes from planned maintenance the response carries the codeMAINTENANCE_MODEand nothing was processed; otherwise checkcodes, and read the endpoint’s own503description where it has one — a few requests may have partially completed and are not safe to repeat.
| 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. |
| 503 - Service Unavailable | Tilia is temporarily unable to process the request. Whether a retry is safe depends on the endpoint — read its own 503 description where one is documented. |
In addition to the HTTP status code, most of our endpoints return additional information describing the errors.
status: The status of the request. Typically returnsSuccessorFailure.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"
}
}
}