Missing documentation of error messages for import source mapping endpoint in Jira Assets

Jira Development Jira Cloud
, , ,
1

Hey, I’m missing some documentation of error messages when working with Jira Assets REST API and the /importsource/<id>/mapping endpoint. In case of a wrong schema, the endpoint returns 400 Bad Request with a JSON payload including error codes that point to the location where the error popped up. This is already quite helpful :slight_smile: However, in the beginning you might not know the meaning of these error codes or you wonder why an error message still appears even if you have updated your schema.

Is there an official documentation explaining these error codes? I couldn’t find one in the REST API docs. So far, I discovered the following error codes and potential explanations:

  • SCHEMA_INVALID_EXTERNAL_ID: occurs when an external id is already in use by another object type (important note: external id’s must be unique across all schemas)
  • EXTERNAL_ID_MISMATCH: occurs when an object type already exists with a certain name but the external id from your schema is different than the one from the existing object type (see also this community topic)
  • UNKNOWN_EXTERNAL_ID_MAPPING: I have no idea :woman_shrugging:
  • MAPPING_INVALID_EXTERNAL_ID: you defined a mapping and it references an external id but the external id does not exist (or is defined in a different schema?).
  • DUPLICATE_EXTERNAL_ID_ILLEGAL: occurs when two or more object types with the same external id have been defined
  • UNKNOWN_REFERENCE: occurs when a reference attribute refers to another object type that is not defined in the schema which you are uploading.
  • REFERENCED_OBJECT_TYPE_CHANGED: occurs when you try to upload a schema that contains two object types (one references another) and the object types have been created before (i.e. same externalId). In my cases, this error message never made any sense to me because I haven’t updated the object types. I just had to include them in the schema because otherwise I got another error like UNKNOWN_REFERENCE.

I hope this list helps a few others of you. Would be great to see this in the REST API docs as well.

4 Likes