Errors

For API responses, we use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a named calendar could not be found, etc.), and codes in the 5xx range indicate an error with our servers.

Common responses #

200 OK #

The request was successful.

202 Accepted #

The request has been accepted for processing.

400 Bad Request #

The request was refused. Only used for requesting an access token and refreshing an access token as mandated by RFC 6749.

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

402 Payment Required #

The request was refused as your plan does not include the required feature.

403 Forbidden #

The request was refused as the provided authorization credentials were recognized but do not grant sufficient privileges.

You will need to make an additional authorization request for the scope required for the forbidden request.

404 Not Found #

The resource, such as a calendar, could not be found.

422 Unprocessable #

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if when creating an event you omitted the required event_id field, you would receive a response like:

{
  "errors": {
    "event_id": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.

423 Locked #

This is returned when we do not have credentials available for the underlying provider and the request made requires active credentials to succeed.

We will have already sent the user an email requesting they relink to give us new credentials but you may wish to prompt them to relink as well.

429 Too Many Requests #

You’ve exceeded your rate limits. By default these are 50 requests per second and 500 requests within a 60 second window.

Your code should stop making API requests temporarily when encountering such a response.

500 Server Error #

The request was unable to be processed due to an error with our servers.