Exceptions for 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.

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 https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/1966080093/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

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


SERVER DOCUMENTATION (On Cloud? Go here.)
Have questions? Contact our Service Desk for help anytime.