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.