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.
  • 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.

Here is a full list of possible error codes:


Error code

Description

accepted

Must be accepted.

after

Must be after %{restriction}.

already_actioned

This action has already taken place.

at_least_one

At least one %{model} must exist.

before

Must be before %{restriction}.

blank

Can't be blank.

cannot_be_changed_to_an_archived_resource

Cannot be changed to an archived resource.

cannot_contain_duplicates

Cannot contain duplicates: %{duplicates}.

cannot_contain_itself

Cannot contain itself.

cannot_disable_only_active

This is the only %{model} and cannot be disabled.

cannot_remove_default

Cannot remove default %{model}.

cannot_remove_when_in_use

Cannot remove %{model} as it is currently in use.

disabled

Is disabled.

empty

Can't be empty.

end_scheduled_must_be_after_start_scheduled

Must be after Start Scheduled.

exclusion

Is reserved.

expired

Has expired, please request a new one.

graph_has_orphans

Orphan relationship(s) found: %{orphans}.

graph_is_cyclic

Cyclic relationship(s) found: %{cycles}.

greater_than

Must be greater than %{count}.

greater_than_or_equal_to

Must be greater than or equal to %{count}.

icon_must_be_unique

%{model} icon and color combination must be unique. Your chosen selection is already in use, please amend and try again.

inclusion

Is not included in the list

invalid

General invalid data error. See error message for details.

invalid_association_state

Associated object is invalid.

invalid_constraint

Does not match constraints.

is_at

Must be at %{restriction}.

less_than

Must be less than %{count}.

less_than_or_equal_to

Must be less than or equal to %{count}.

max_size_error

File size should be less than %{max_size}.

max_successors_exceeded

Too many successors found for %{ids} (the limit is %{limit} successors).

min_size_error

File size should be greater than %{min_size}.

missing_association

Association is missing.

missing_association_permission

You need permission on the target association.

missing_custom_field_value

Missing required response for ‘%{name}’.

must_be_empty

Must be empty.

must_be_in_the_past

Must be in the past.

must_match_workspace

Must match Workspace.

not_a_number

Is not a number.

not_an_integer

Must be an integer.

not_editable

%{model} is not editable.

not_email

Address is invalid. Please correct this field and try again.

not_found

Not found.

on_or_after

Must be on or after %{restriction}.

on_or_before

Must be on or before %{restriction}.

other_than

Must be other than %{count}.

required

Must exist.

taken

Must be unique.

too_deep

%{model} cannot be nested this deep.

too_long

Is too long (maximum is %{count} characters).

too_many

Maximum number of %{model} records already reached.

too_short

Is too short (minimum is %{count} characters).

unauthorized

Authorized users only.

variable_not_found

%{variable} is invalid or does not exist, refer to Cutover Developer documentation for correct syntax.

visibility_charge

Unable to change the visibility of this %{model} as it has been used.

wrong_length

Is the wrong length (should be %{count} characters).

wrong_task_id

Task #%{task_internal_id} can't be found.

comments.create.runbook_archived

Unable to add a comment to an archived runbook.

folders.archive.contains_unarchived_events

This folder contains unarchived events.

folders.archive.contains_unarchived_runbooks

This folder contains unarchived runbooks.

runbook.cannot_be_template_with_event

Unable to create an event from a template runbook.

runbook.cannot_remove_template_when_in_use

This Runbook Template has already been used and must remain as a Template.

runbook.cannot_switch_from_change_request_runbook_type

Unable to switch runbook type for a Change request runbook.

runbook.cannot_update_template_status_on_non_template

Unable to update template_status on a non-template runbook.

runbooks.start.archived_task_types

%{count} users in this runbook are archived.

runbooks.start.archived_users

%{count} users in this runbook are archived.

runbooks.start.change_requests_outside_window

%{count} change requests outside of the change window.

runbooks.start.empty_teams

%{count} teams in this runbook are empty.

runbooks.start.invalid_fixed_end_tasks

%{count} tasks in this runbook have no due date defined.

runbooks.start.late_tasks

%{count} tasks have a start time in the past. This is likely to result in a delay starting the runbook while these are processed.

runbooks.start.linked_parent_task_not_startable

The linked task is not startable.

runbooks.start.linked_runbook_errors

%{count} tasks have linked runbooks which contain errors.

runbooks.start.linked_runbook_status

%{count} tasks have linked runbooks which are either still a template or have been archived.

runbooks.start.linked_task_types_without_linked_runbooks

%{count} tasks which are of linked task type but has no template or runbook attached.

runbooks.start.max_tasks_exceeded

Your runbook has %{tasks_count} tasks, but the max allowed on Runbook Start is %{max_tasks}.

runbooks.start.parent_runbook_status

Parent runbook %{runbook_id} has not started yet.

runbooks.start.tasks_with_empty_comms_messages

%{count} comms tasks in this runbook don't have content

runbooks.start.tasks_with_no_recipients

%{count} comms tasks in this runbook don't have recipients

runbooks.start.unapproved_change_requests

%{count} change requests not confirmed. These will not be automatically updated to 'Implementation in Progress'

runbooks.start.unassigned_tasks

%{count} tasks in this runbook are unassigned

runbooks.start.users_not_accepted

%{count} users in this runbook have not accepted their invite

runbooks.start.users_not_in_workspace

%{count} users in this runbook are no longer on this workspace.

runbooks.start.users_with_no_phone

%{count} users in this runbook have not entered a phone number.

runs.create.cannot_run_template_live

Unable to start a live run as the runbook is a template.

runs.create.event_not_published

Unable to start a live run as the event has not been started.

task.already_started

Task has already been started.

task.not_editable

Task is not editable.

task.not_finishable

Task is not finishable.

task.not_startable

Task is not startable.

task.same_must_finish

The user that started must finish the task.

task.user_already_finished

User has already finished the task.

task.user_already_started

User has already started the task.

task.user_not_assigned

User is not assigned to the task.

users.archive.unable_to_archive_self

You cannot archive your own user account.