Skip to content

Errors

Overview

Errors with the API can happen on occasion. Please refer to the status request to figure out whether the API is up and running or not. Otherwise, Theca will always return an error code with an explanation of what went wrong with a result. Errors are always returned as JSON coded responses. These contain additional links to the API documentation and in some cases a description of the error.

Tip

Ensure the resilience of your website by planning error handling into your implementation plan. Account for scenarios where our services timeout or return error results.

example of error response for request /search instead of /v1/search
{
    "timestamp": "2023-03-07T12:43:28",
    "statusCode": 404,
    "status": "Not Found",
    "path": "/search",
    "documentation": "https://docs.theca.com/api/search/parameters",
    "help": "https://docs.theca.com/errors/codes#notfound"
}

Codes

This is a list of descriptions all normal errors or exceptions that is returned by the system.

Invalid request

This error occurs when a client's request does not meet the APIs expectations. Double-check the structure and content of your request to ensure they match what the API is expecting.

Too many requests

This error is triggered when the client sends too many requests within a certain period for a given Theca-User-Token. It's related to rate limiting implemented by the server to control bot traffic. If you encounter this error for likely human traffic, please contact support.

Missing query parameter

This error usually occurs when the system expects a certain query parameter to be included in the client's request. Ensure that your request includes all the necessary parameters in the correct format before sending.

Wrong format query parameter

This error is thrown when a query parameter has the correct key but the value is formatted incorrectly or is of the wrong type. Please validate that your parameters are formatted according to the API's specification.

Unauthorized

This error occurs when the authentication required for a request is either missing or invalid. Make sure to include a valid Theca-Client-Token HTTP header in your requests that require authentication.

Forbidden

This error is served when your Theca-Client-Token is valid but do not have permissions to access the requested resource. Ensure that your user role or client token has the necessary rights to perform the action you are trying to execute by checking the whoami request

Conflict

This error happens when the requested resource has undergone recent updates or deletions, rendering it no longer valid. As a result, the system cannot process requests related to it. If this is part of a search request, the original query will need to be performed again to get new items. Repeating the same url request will not work.

Not found

This error means that the resource requested by the client isn't available or isn't recognized by the system. Check if your request is referring to the correct and existing resource in the system and that the API endpoint is correct.

Internal server error

This kind of error happens when an unexpected issue arises in the server while processing the client's request. The specific reason causing this error can be diverse. You might have to wait until the server issue is resolved.