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.

Example

JSON

{message:"This is an exception message"}

General exceptions

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

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. Example 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
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. Example 2021-05-28T15:50-04:00 Some parsing limitations cause some ISO8601 formats to be rejected. To specify a time and time zone, use the format in the example above.
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.

All general exceptions apply.

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.

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.

All general exceptions apply.

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. Example 2021-05-28T15:50-04:00 Some parsing limitations cause some ISO8601 formats to be rejected. To specify a time and time zone, use the format in the example above.
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.

All general exceptions apply.

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.

All general exceptions apply.

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.

All general exceptions apply.

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.

Strict values are case sensitive.

Checklist parameters

Field		Values
issueViewDisplayMode		CustomField IndependentPanel SidebarPanel
summarySource		AllItems MandatoryItems
bannerParameters	appearance	Normal Subtle
bannerParameters	type	Custom Progression
assigneeDisplay		Avatar Name Initials AvatarAndName AvatarAndInitials
defaultHeaderCollapsedState		Expanded Collapsed CollapseCompletedSections

Proxy parameters

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

Permission schemes

These exceptions are specific to the /permissions APIs.

All general exceptions apply.

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	The scheme name is mandatory	The `name` field is null, empty or unspecified.

Permission rules

These exceptions are specific to the /permissions/{permissionSchemeId}/rules APIs.

All general exceptions apply.

Response code	Message example	Cause
400	The permission rule's user identifier is mandatory.	The `who` field is null or unspecified.
400	The permission rule's user identifier type is mandatory.	The `who` field isn’t empty but its `type` field is null, unspecified or invalid.
400	The permission rule's user identifier value is mandatory.	The `who` field’s `type` requires a value in the `value` field, but it is null or unspecified.
400	The permission rule's ability is mandatory.	The `what` field is null, unspecified or invalid.
400	The permission rule condition's type is mandatory.	There is at least one condition with a null, unspecified or invalid `type` field.
400	The permission rule condition's values are mandatory.	There is at least one condition with a null, empty or unspecified `values` field. The `values` field is a table of String values.

Strict rule values

Identifier types (who.type)

Some identifiers will require a value. If no value is specified, the endpoint will fail when updating or creating.

Key	Requires a value?
ANY_LOGGED_IN_USER	NO
USER_GROUP	YES A user group’s ID.
PROJECT_ROLE	YES A project role’s ID.
ISSUE_REPORTER	NO
ISSUE_ASSIGNEE	NO
CHECKLIST_ITEM_ASSIGNEE	NO
SINGLE_USER	YES A user’s username.

Permissions (what)

Key	Description
ALL	Ability to do everything with checklist.
EDIT_CHECKLIST	Ability to build and edit the contents of a checklist.
CREATE_ITEM	Ability to create a checklist item.
EDIT_ITEM	Ability to edit a checklist item name and convert to header.
DELETE_ITEM	Ability to delete a checklist item.
REORDER_ITEM	Ability to move a checklist item in the list.
WORK_ON_ITEM	Ability to work with existing checklist items.
CHECK_ITEM	Ability to mark a checklist item complete.
CHANGE_STATUS	Ability to change the status of a checklist item.
CHANGE_ASSIGNEE	Ability to modify the user assigned to a checklist item.
CHANGE_PRIORITY	Ability to modify the priority of a checklist item.
CHANGE_DUE_DATE	Ability to modify a due date of a checklist item.
TOGGLE_MANDATORY	Ability to toggle an item mandatory or optional.
INTERACT_WITH_TEMPLATES	Ability to interact with checklist templates.
IMPORT_TEMPLATE	Ability to import a template into a checklist.
MANAGE_OWNED_TEMPLATES	Ability for users to create, edit and delete templates of which they are the owner. Users that create templates from checklists in issues are automatically set as owners.
CONVERT_TO_ISSUE	Ability to convert a checklist item into a Jira issue.

Condition type (when.type)

Key	Required value
PROJECT	A project ID
ISSUE_TYPE	An issue type ID
WORKFLOW_STATUS	A workflow status ID
WORKFLOW_STATUS_CATEGORY	A workflow status’ category ID