Exceptions for configuration REST APIs

This page covers all the errors that can occur when working with our configuration REST APIs.

Structure of exceptions

The response for exceptions is always a JSON object with a single message property.

{message:"This is an exception message"}

General exceptions

These exceptions can occur in most, if not all, REST APIs.

Response code	Message example	Cause

Response code	Message example	Cause
400	The specified field configuration is not for a Checklist for Jira custom field.	The specified field configuration ID is not for a valid Checklist for Jira field. With the exception of the `/parameters` API, no other API accepts a Proxy custom field’s configuration ID.
400	The payload must be of a valid JSON format.	The payload provided could not be parsed as a JSON object.
400	The 'X' field is invalid for the 'Y' parameter and must not be specified.	The JSON payload contains a field that is not recognized in the requested API. Sending a `test` field in the `globalitems` API. Calculated fields like the `id` or the `version` fields are ignored from the payload and will not cause a failed call.
400	The 'X' field for the 'Y' parameter should be an object.	The specified field requires a JSON object value, but was provided something else.
400	The 'X' field for the 'Y' parameter should be an array.	The specified field requires a JSON array value, but was provided something else.
401	-	The user who is calling the API is not an administrator.
403	The Checklist Add-on evaluation license is currently expired. Please purchase a new license.	You do not have a valid Checklist for Jira license.
404	The specified field configuration was not found.	The specified field configuration ID does not exist.
404	The record with ID 'X' was not found.	No record was found for the get or put request’s specified ID in the provided field configuration.

Global item exceptions

These exceptions are specific to the /globalitems APIs.

All general exceptions apply.

Response code	Message example	Cause

Response code	Message example	Cause
400	An item name cannot be empty.	An item cannot be created without a name, nor can it be updated to have an empty name.
400	The due date is not in a valid ISO format: 'X'.	The due date value could not be parsed to a date. We suggest using an ISO8601 format with delimiters. 2021-05-28T15:50-04:00
400	You cannot set a Due Date on a checklist item, the feature is disabled.	The item has a due date, but the `canSetDueDate` feature is disabled. You need to either remove the due date or enable the feature.
400	You cannot set a Priority on a checklist item, the feature is disabled.	The item has a priority, but the `canSetPriority` feature is disabled. You need to either remove the priority or enable the feature.
400	You cannot set a Status on a checklist item, the feature is disabled.	The item has a status, but the `showStatusMenu` feature is disabled. You need to either remove the status or enable the feature.
400	You cannot set an Assignee to a checklist item, the feature is disabled.	The item is assigned, but the `canAssignUsers` feature is disabled. You need to either remove the assignment or enable the feature.
400	Status ID 'X' is not valid. Status ID must exist in the checklist's status parameters.	The specified status ID was not found in the configured status IDs. See the configured statuses in the parameters for the list.
400	Priority ID 'X' is not valid. Priority ID must exist in the Priority Scheme.	The specified priority ID was not found in the priority scheme.

Default local item parameter exceptions

These exceptions are specific to the /defaultlocalitemparameters APIs.

Response code	Message example	Cause

Response code

Message example

Cause

400

A template is required.

When the fromTemplate field is set to true, the templateId field cannot stay null.

400

No template with ID 'X' exists.

No template exists in the database with the specified ID.

400

No template was found for field configuration 'X' with the ID 'Y'.

The template with the specified ID exists, but does not match the field configuration being configured.

The template is most likely configured for another field configuration.

Default local item exceptions

These exceptions are specific to the /defaultlocalitems APIs.

Response code	Message example	Cause

Response code	Message example	Cause
400	An item name cannot be empty.	An item cannot be created without a name, nor can it be updated with an empty name.
400	The due date is not in a valid ISO format: 'X'.	The due date value could not be parsed to a date. We suggest using an ISO8601 format with delimiters. 2021-05-28T15:50-04:00
400	You cannot set a Due Date on a checklist item, the feature is disabled.	The item has a due date, but the `canSetDueDate` feature is disabled. You need to either remove the due date or enable the feature.
400	You cannot set a Priority on a checklist item, the feature is disabled.	The item has a priority, but the `canSetPriority` feature is disabled. You need to either remove the priority or enable the feature.
400	You cannot set a Status on a checklist item, the feature is disabled.	The item has a status, but the `showStatusMenu` feature is disabled. You need to either remove the status or enable the feature.
400	You cannot set an Assignee to a checklist item, the feature is disabled.	The item is assigned, but the `canAssignUsers` feature is disabled. You need to either remove the assignment or enable the feature.
400	Status ID 'X' is not valid. Status ID must exist in the checklist's status parameters.	The specified status ID was not found in the configured status IDs. See the configured statuses in the parameters for the list.
400	Priority ID 'X' is not valid. Priority ID must exist in the Priority Scheme.	The specified priority ID was not found in the priority scheme.

Template exceptions

These exceptions are specific to the /templates APIs.

Response code	Message example	Cause

Response code	Message example	Cause
400	The value provided for the template items is not a valid checklist item JSON array.	The value passed to the `itemsJson` field could not be parsed to a checklist item array.
400	At least one template item must be provided.	The JSON array passed to the `itemsJson` field is empty.

App parameter exceptions

These exceptions are specific to the /configuration APIs.

Response code	Message example	Cause

Response code	Message example	Cause
400	The history date format is required.	A null or empty value was passed to the `historyDateFormat` field.
400	The history date format 'X' is invalid.	The value used for the `historyDateFormat` field is not a valid date format.

Parameter exceptions

These exceptions are specific to the /parameters APIs.

Response code	Message example	Cause

Response code	Message example	Cause
400	The value indicated for field 'X' in the 'Y' is invalid.	The value provided for the field is invalid. See the table below for the available values for certain fields.
400	Please select a project role which will have access to the checklist.	If the `limitEditionWithRoles` feature is enabled, the `editRoleIds` field must contain at least one role ID.
400	Please enter a number greater than or equal to 1.	If the `showMore` feature is enabled, a number greater than or equal to 1 is required in the `showMoreCount` field.
400	This is not a number. Please enter a number greater than or equal to 1.	The value provided to the `showMoreCount` is either not a number or has a value outside of a signed integer’s limits.
400	Number of columns should be 5. Invalid number of columns: 'X'	The status CSV has a row with a number of columns other than 5.	For more information, see Editing statuses \| Editing statuses in CSV format.
400	The ID is mandatory.	A status was provided with no ID.
400	The name is mandatory.	A status was provided with no name.
400	Specified status style is invalid: 'X'	A status with an invalid status style was provided.
400	Specified completion behavior is invalid: 'X'	A status with an invalid completion behavior was provided.
400	Specified status behavior is invalid: 'X'	A status with an invalid status behavior was provided.
400	Status ID cannot be 'none' because it is a reserved keyword.	A status was provided with the `none` ID.
400	Status ID cannot contain spaces.	A status was provided with an ID that contains spaces.
400	The specified ID 'X' is already used. Status IDs must be unique.	More than one status was provided with the same ID.
400	The selected behaviors are invalid. If the status behavior is 'Remove', the completion behavior must be 'Incomplete'.	A status was provided with the `Remove` status behavior and a completion behavior other than `Incomplete`.
400	The selected behaviors are invalid. If the status behavior is 'Reset', the completion behavior must be 'Complete'.	A status was provided with the `Reset` status behavior and a completion behavior other than `Complete`.

Strict parameter values

Some parameters do not accept custom values. These strict values are listed below.

Checklist parameters

Field		Values

Field		Values
issueViewDisplayMode		CustomField IndependentPanel SidebarPanel
summarySource		AllItems MandatoryItems
bannerParameters	appearance	Normal Subtle
bannerParameters	type	Custom Progression
since 5.2.2 assigneeDisplay		Avatar Name Initials AvatarAndName AvatarAndInitials

Proxy parameters

Field		Values

Field		Values
summarySource		AllItems MandatoryItems
type		Banner Checklist ProgressBar
banner	appearance	Normal Subtle
	prefix	Checkbox Custom CustomFieldName None
	type	Custom Progression
progressBarParameters	labelType	Custom Default None

Checklist for Jira - Server & Data Center Docs