Skip to content

Errors

Errors return a JSON body with a message. Other fields can be present. When parts of a request are wrong, most endpoints list each problem in issues, with its place in the request (path), a code and a message. Other 400 errors have no issues.

{
"message": "The request is invalid.",
"issues": [
{
"path": ["changes", 1, "id"],
"code": "INVALID_REQUEST",
"message": "The same change id is used more than once."
}
],
"public": true
}
  • path points inside the request body, or inside the query for a GET request. It is [] when the problem is the whole body or query, for example with the message At least one filter must be provided.
  • For _sortBy, path includes the index of the wrong value, even when you send one value: ?_sortBy=x gives ["_sortBy", 0].
  • code is stable: build your error handling on it. message explains the problem to a person and can change.
  • Fixing the listed problems can reveal further ones: some checks only run once the others pass.
  • At most 100 INVALID_REQUEST issues are listed.

Codes other than INVALID_REQUEST come only from Create ticket and Update ticket fields.

code Meaning
INVALID_REQUEST The request doesn’t have the expected shape, for example an unknown key, a missing key, too many items or the same change id twice
FIELD_NOT_WRITABLE The field is set by Sitemark, read-only, hidden or not a field of this form
UNSUPPORTED_TYPE The field’s type can’t be written through the API
INVALID_VALUE The value doesn’t fit the field, or it is a TAGS value the key may not set
UNREADABLE_USER The user or group is not of the ticket’s company, or the key can’t see it, or a v2 value names a principal that is not a user or group, or a group without legacy_user_id
REQUIRED A required field is missing. These come in a separate 400 with the message "Required fields are empty.", after the other fields pass.