API Errors

General API Errors

These are the errors we all know and love. They're errors that can happen in most web applications, and they should be straight forward to solve.

Status	Error	Response	Description
400	Bad Request	`{"status_code": 400, "message": "Expected a JSON object.", "error": "bad_request"}`	The request requires a JSON body, but we couldn't parse it. Double check that you're sending a request body and that the body is valid JSON.
401	Unauthorized	`{"status_code": 401, "message": "Unauthorized", "error": "unauthorized" }`	We don't know who you are! Either the request didn't include authentication or the authentication wasn't valid. Double check the user ID and API key, or head to Getting Started for an example.
403	Forbidden	`{ "status_code": 403, "message": "Forbidden", "error": "forbidden" }`	The request included authentication and we know who you are, but you don't have access to the resource. Eg. the calendar or appointment type belongs to another user.
404	Not Found	{ "status_code": 404, "message": "Not Found. Did you mean `/appointments/{id:number}`?", "error": "not_found" }	The requested resource could not be found. Fat fingers happen, so if it looks like a typo we'll do our best to suggest the correct endpoint. Also double check URI IDs, in case the resource legitimately does not exist.
405	Method Not Allowed	`{ "status_code": 405, "message": "Method Not Allowed", "error": "method_not_allowed" }`	The resource exists but the HTTP method is not supported. Not all of our endpoints support the same methods. Check our docs for the methods which are supported.
429	Too Many Requests	`{"status_code": 429,"error": "too_many_requests","message": "Rate limit reached. Limit 10req/s and 20 concurrent connections."}`	Woah there! Our API is currently rate limited to 10 requests a second and 20 concurrent connections from an IP.
500	Internal Server Error	`{ "status_code": 500, "message": "Internal Server Error", "error":"internal_server_error" }`	Something unexpected happened. These errors should not happen, but when they do we'll get notified and be on the case quickly. Feel free to reach out to us at [email protected].

Specific API Errors

Many of our endpoints return specific errors related to that endpoint. These errors will will do their best to include a descriptive message about what went wrong. The error response body looks like this:

{
  "status_code": 400,
  "error": "invalid_name",
  "message": "Can not clear the field \"firstName\"."
}

Status	Error	Response	Description
400	Bad Request	`{"status_code": 400, "message": "Can not clear the field \"firstName\".", "error": "invalid_name"}`	General validation errors such as unexpected values or missing required fields will generate 400 errors. We'll give a descriptive message about what went wrong to help you resolve it.
422	Unprocessable Entity	`{"status_code": 422, "message": "End is before start.", "error": "invalid_time"}`	Left over from before RFC 7231 opened up the description of the 400 status code, our `POST /blocks` endpoint returns 422 error on time validation errors.

750 — Attributed to Rogério Vicente & Tonomi - https://http.cat/