Skip to main content
Skip table of contents

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.

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

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

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.