Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. TimeZest will always try to return descriptive error messages when it is unable to act on a request.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong.

Status codes

Here is a list of the different categories of status codes returned by the TimeZest API. Use these to understand if a request was successful.

  • Name
    2xx
    Type
    Description

    A 2xx status code indicates a successful response.

  • Name
    4xx
    Type
    Description

    A 4xx status code indicates a client error — TimeZest was unable to act on the request you made.

  • Name
    5xx
    Type
    Description

    A 5xx status code indicates a server error where something has gone wrong at TimeZest.

Invalid API Key

TimeZest will return this error with a HTTP status of 401 either when no API key is provided, or the API key which is provided is not a valid one.

To fix, ensure that you're using a valid API key from the API Keys page, and that you're sending it with the Authorization HTTP header, and prefixing it with the keyword Bearer.

Error response

{
  "error": "Unauthorized. No valid API key provided"
}

API Key missing permissions

TimeZest will return this error with a HTTP status of 403 when attempting to make a request which requires a level of premission which the API key in use has not been granted - for example, trying to create a new scheduling request with a read-only API key.

To fix, either edit the permissions of the API key in the API Keys page, or create a new API key with the correct permissions.

Error response

{
  "error": "Unauthorized. The provided API key does not have sufficient
  permission to perform this action."
}

Rate Limit Exceeded

TimeZest will return this error with a HTTP status of 429 when you make too many requests to the API in too short a time period.

Each account can make a maximum of 180 requests in any 60-second period. This limit is the combined number of requests for all API keys, not per API key. To fix this issue, slow down the rate at which you make requests to the TimeZest API.

Error response

{
  "error": "Rate limit exceeded. A maximum of 180 requests in any 60-second
  period is permitted."
}

Invalid Pagination Parameters

TimeZest will return this error with a HTTP status of 400 when both pagination parameters are used in a single request.

TimeZest's cursor-based pagination returns pages with a fixed number of items, and only one of the starting_after or ending_before parameters can be used in each request. To fix this issue, modify the parameters being passed with the request.

Error response

{
  "error":"Invalid pagination parameters. Only one of the 'starting_after'
  and 'ending_before' parameters may be used for each request."
}

Invalid TQL

TimeZest will return this error with a HTTP status of 400 if it cannot parse the TQL string provided with the filter parameter.

To fix this, correct the TQL string so that it is valid TQL. The error message will include additional details about the exact error encountered.

Error response

{
  "error":"Invalid TQL: {Detailed error message}."
}