Error codes

We use conventional HTTP response codes to indicate the success or failure of an API request. There are three general response code ranges you can expect to receive:

1. 2xx indicates a successful request.

2. 4xx indicates a failed request due to a problem with the information provided. (For example, a request parameter was not included or a specified task was not found in a runbook).

3. 5xx indicates an error with our servers. Note that these errors will be rare.

The following standard HTTP status codes are used in the API:

  • 200 OK
  • 201 Created
  • 400 Bad Request: The URL, header, or request body has invalid syntax or is malformed.
  • 401 Unauthorized: Check the bearer authentication token is correct.
  • 403 Forbidden: The permissions associated with the token are not sufficient to access this resource.
  • 404 Not Found: The resource requested or a dependent resource is not accessible (never existed, archived or deleted).
  • 405 Method Not Allowed: This endpoint has not been implemented yet in the API. Also see 501.
  • 422 Unprocessable Entity: The request was understood but could not be fulfilled due to validation rules.
  • 429 Too Many Requests: Requests from this token or IP have been rate limited. Please apply exponential back off. Contact your Customer Success Manager if you would like to discuss your rate limit.
  • 500 Internal Server Error: An unexpected error within the Cutover API.
  • 501 Not Implemented: Usually a sign that the Core application is not up to date.
  • 503 Service Unavailable: Could not connect the upstream application (typically Core).
  • 504 Gateway Timeout: Core application exists but is timing out.


4xx HTTP response codes return a specific error code and accompanying detail (a description of the error) in the body of the response. 

For example, this is a 404 response body:

"errors": [
   "title": "Not Found",
   "detail": "This link is not valid. This may be because the item is archived or you do not have access to it.",
   "code": "not_found"

The "title" and "detail" strings may change or get translated in future API versions, therefore we recommend using the "code" field to map errors programmatically.

For a full list of our error codes, please click here.