Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen and we spent a lot of time making sure that error messages are as clean as possible. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful (i.e. not a HTTP 2XX response), you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Status codes

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

  • Name
    2xx
    Description

    A 2xx status code indicates a successful response.

  • Name
    4xx
    Description

    A 4xx status code indicates a client error. This means that there's a problem with your access token, the endpoint you requested or the query/body parameters are invalid. We try to be as specific as possible with our error messages.

  • Name
    5xx
    Description

    A 5xx status code indicates a server error. That means we did something wrong. We'll be notified of these and will start fixing them immediately.

The Error model

  • Name
    type
    Type
    string
    Description

    The high level type of the error

  • Name
    code
    Type
    string
    Description

    A short string with a brief explanation

  • Name
    message
    Type
    string
    Description

    A human readable description

  • Name
    documentation_url
    Type
    string?
    Description

    A link to the calapi documentation where you are likely to receive further information about fixing the error.

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "The calendar with id 'cal_mJUHrGXZBZ' could not be found.",
    "documentation_url": "https://docs.calapi.io/calendars"
  }
}

Error types

Whenever a request is unsuccessful, the Calapi API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is a list of the three error types supported by the Calapi API — use these to understand what you have done wrong.

  • Name
    invalid_request_error
    Description

    This means that you made an error in your request.

  • Name
    internal_error
    Description

    This means that we made an error.

  • Name
    provider_error
    Description

    This means that the calendar provider returned an error that we didn't expect.

Invalid Request Errors

Here is a list of the invalid request error codes returned by the Calapi API — use these to understand the error response.

  • Name
    validation_error
    Description

    A validation error is returned if a request was made with invalid parameters. You will have to change your request body or query parameters before trying again. The validation error is special because it will include additional information in the details property which explain the problem more precisely.

Example validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Your request has failed validation.",
    "type": "invalid_request_error",
    "details": [
      {
        "message": "Field 'color' is not valid for this provider. Please review https://docs.calapi.io/colors",
        "source": "/color"
      }
    ]
  }
}
  • Name
    invalid_authorization_header
    Description

    The Authorization header must conform to the following format: Bearer API_TOKEN

  • Name
    insufficient_permissions
    Description

    You don't have the necessary permissions to perform this request. Either you're trying to modify a calendar using a read-only Calapi token or you're trying to modify a calendar that is read-only (for example a remote ICS calendar).

  • Name
    not_found
    Description

    The requested resource cannot be found

Provider Errors

Here is a list of the provider error codes returned by the Calapi API — use these to understand the error response.

  • Name
    provider_error
    Description

    This is a generic error code. Look to the message to see what went wrong. Ideally you shouldn't ever see this but it's possible that certain edge cases haven't been handled by us correctly so we'll forward the error message from the provider to you.

  • Name
    provider_auth_error
    Description

    This error code indicates that Calapi was unable to authenticate with the provider's APIs. This shouldn't really happen but if you disconnect Calapi in the provider's settings you may see this. The solution is just to reconnect the provider.

Was this page helpful?