Error codes

Last Updated: December 6th, 2023

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.

Example

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.