Handle Import Service API errors and exceptions

The Import Service API throws two type of errors:

Job level errors - are severe enough to cause the entire import job to fail. These errors can be found in the GetDetailsAsync endpoints for IImportJobController and IImportSourceController.
Item level errors - are specific to rows within the data source being imported. Unlike job level errors, item level errors do not cause the entire import job to fail. Instead, they are logged and the import process continues with the next row from the load file. Item level errors can result in whole record, meaning document or RDO, not being imported to the workspace or the record in the workspace can be incomplete. You can retrieve all item level errors that occurred during the import process from GetItemErrorsAsync endpoint for IImportSourceController.

Retrieving errors

Error handling in Import Service returns error codes and error messages:

in every response for failed HTTP request

curl

Copy

1
2
3
    curl -X GET 'https://relativity.roadie.so/Relativity.REST/api/import-service/v1/workspaces/10000/import-jobs/00000000-0000-0000-0000-000000000000/sources/00000000-0000-0000-0000-000000000000/details'
    -H 'accept: application/json'
    -H 'X-CSRF-Header: -'

JSON response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
"Value": {
    "State": "Failed",
    "DataSourceSettings": {
        Path": "file.dat",
        "EndOfLine": "Windows",
        "Type": "LoadFile",
        "FirstLineContainsColumnNames": true,
        "StartLine": 0,
        "Encoding": "utf-8"
        "ColumnDelimiter": "a",
        "QuoteDelimiter": "b",
        "NewLineDelimiter": "c",
        "MultiValueDelimiter": "d",
        "NestedValueDelimiter": "e"
    },
    "JobLevelErrors": [
    {
    "LineNumber": -1,
    "ErrorDetails": [
            {
                "ColumnIndex": -1,
                "ErrorCode": "S.RD.EXT.0217",
                "ErrorMessage": "Cannot read Data Source. Could not open file for reading by RestartableStream.",
                "ErrorMessageTemplate": "Cannot read Data Source. Could not open file for reading by RestartableStream.",
                "ErrorProperties": {}
            }
        ]
    },
    "CreatedBy": 777,
    "CreatedOn": "2022-10-18T15:09:12.69",
    "LastModifiedBy": 777,
    "LastModifiedOn": "2022-10-18T15:10:00.497"
},
"IsSuccess": true,
"ErrorMessage": "",
"ErrorCode": "",
"ImportJobID": "00000000-0000-0000-0000-000000000000"
}

when requested by user for all job level errors that occurred during importing of particular data source

curl

Copy

1
2
3
    curl -X GET 'https://relativity.roadie.so/Relativity.REST/api/import-service/v1/workspaces/10000/import-jobs/00000000-0000-0000-0000-000000000000/sources/00000000-0000-0000-0000-000000000000/itemerrors?start=0&length=10'
    -H 'accept: application/json'
    -H 'X-CSRF-Header: -'

JSON response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
"Value": {
    "DataSourceID": "00000000-0000-0000-0000-000000000000",
    "Errors": [
    {
        "ErrorDetails": [
        {
            "ColumnIndex": 1,
            "ErrorCode": "S.LN.INT.0001",
            "ErrorMessage": "Error message.",
            "ErrorMessageTemplate": "Template error message.",
            "ErrorProperties": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
            }
        }
        ],
        "LineNumber": 1
    }
    ],
    "TotalCount": 1,
    "NumberOfSkippedRecords": 0,
    "NumberOfRecords": 1,
    "HasMoreRecords": false
},
"IsSuccess": true,
"ErrorMessage": "",
"ErrorCode": "",
"ImportJobID": "00000000-0000-0000-0000-000000000000"
}

Error code structure

Error codes returned from the Import Service API endpoint has the following structure, [Resource].[Action].[ErrorType].[ErrorNumber]. For example, J.CR.VLD.1501 is returned when a job cannot be created because validation has failed.

Resources

The possible resource codes for an error code are listed in the following table:

Resource code	Description
J	Job
C	Document Configuration
S	Source
E	ItemErrors
R	RDO Configuration

Actions

The possible action codes for an error code are listed in the following table:

Action code	Description
BEG	Begin
CR	Create
CNL	Cancel
END	End
GET	Get
GET_COL	Get columns
GET_CFG	Get config
GET_DAT	Get data
GET_DTLS	Get details
GET_PRG	Get progress
LN	Line
PS	Pause
RD	Read
RES	Resume
RUN	Run

Error types

The possible error types for an error code are listed in the following table:

Error type code	Description
INT	Internal service error
EXT	External dependency error
VLD	Validation error

Error numbers

Error numbers have four digits. Digits on the first and on the second position have specific meanings.

The first digits meaning is the same for all error types.

Resource code	Description
0XXX	General error
1XXX	Job related error
2XXX	Configuration related error
3XXX	Source related error
4XXX	ItemErrors related error

The second digits meaning differs for each error type.

Error Type	Resource code	Description
INT	X[0-9]XX	Service errors
EXT	X[0-9]XX	Runtime errors
VLD	X0XX	Invalid input data
VLD	X5XX	System state does not allow to execute request
VLD	X6XX	Data in the system does not exist
VLD	X7XX	Data in the system is incorrect
VLD	X9XX	Data in the system is corrupted

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet