Error reporting categories

This section describes the error categories and associated error codes that can be returned in the JSON error report document for z/OS® data set and file REST interface requests. This document is described in Error report document.

Table 1. Error categories for z/OS data set and file REST interface operations
Category	Ordinal Value	Description	Where the error details are described
Service	1	Errors produced or detected in the service layer.	Category 1 — Service error
Message queue	2	Errors produced or detected by the message queue.	Category 2 — Message queue error
CEA	3	Errors produced or detected by the common event adapter (CEA) interface.	Category 3 — Common event adapter (CEA) error
ISPF	4	Errors produced or detected by the Interactive System Productivity Facility (ISPF) interface.	Category 4 — ISPF error
CSI	5	Errors produced or detected by the catalog search interface (CSI).	Category 5 — Catalog Search Interface (CSI) error
Read or write function	6	Errors returned from an attempted read or write request.	Category 6 — Read or write error
JSON	7	Errors produced or detected when parsing JSON.	Category 7 - JSON Parser Conditions
XL C/C++	8	Errors produced or detected by z/OS XL C/C++	Category 8 - z/OS XL C/C++ Conditions
Unexpected	16	Unexpected errors detected.	Category 9 — Unexpected error

Category 1 — Service error

Table 2 shows the possible conditions for this error category.

Table 2. Category 1 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
4	1	`%s`	The request specified a URL that is not valid. %s indicates which parts of the URL are invalid, such as path information, data set name and volume serial.
4	2	`Invalid data set name length.`	The request specified a data set name length that is not valid. Note that data set names cannot exceed 44 characters in length.
4	3	`The specific data set name is invalid.`	The request specified a data set name (dslevel) that is not valid.
4	4	`Retrieving USS files should start with absolute path.`	The requested file cannot be retrieved because the request is missing an absolute path name, which is required. When retrieving UNIX files, the file path must be an absolute (or fully-qualified) path name, rather than a relative (or partially-qualified) path name.
4	5	`Length of USS path is invalid.`	The request specified a UNIX file path length that is not valid.
4	6	`The specific path is invalid.`	The request specified a UNIX file path that is not valid.
4	7	`The specific volser is invalid.`	The request specified a volume serial (volser) that is not valid.
4	8	`File not found.`	The request specified a file that does not exist.
4	9	`Incorrect content type.`	The request specified an unsupported content type.
4	10	`Unrecognized HTTP method.`	The request is not recognized as a supported HTTP method.
4	11	`POST method is not supported.`	The POST method was specified, however POST is not a supported HTTP method.
4	12	`Incorrect attribute was specified.`	The request contained one or more attributes that are not valid.
4	13	`Incorrect parameter was specified.`	The request contained one or more parameters that are not valid.
4	14	`The specific JSON data in the request is invalid.`	JSON data in the request is invalid.
4	15	`The size of the data to be written is invalid.`	The size of the data to be written is invalid.
4	16	`Request content-length must be specified. Request content-length was too long. Request content was longer than specified content-length.`	Only used in ValidateJsonServlet.C.
4	17	`Request document contained invalid JSON.`	Not currently used.
4	18	`Member name is not valid.`	Member name is not valid.
4	19	`Unix file/directory exists.`	Unix file/directory already exists.
8	1	`Unable to get JSON Response.`	Not currently used.
8	2	`Unable to get JSON Response Table.`	Not currently used.
8	3	`Unable to load ISPEXEC.`	The ISPF service route ISPEXEC could not be loaded.
8	4	`Unable to load TSO servlet mappings.`	The servlet dispatcher was not able to load the servlet mappings JSON file.
8	5	`A servlet-mapping was not found for servlet-path.`	A servlet mapping matching the request could not be found. Indicates a servlet-mapping configuration error.
8	6	`ExceptionServlet threw an exception after commit. Servlet failed but could not send error response.`	An exception was thrown by the servlet.
8	7	`TsoServlet already committed.`	An exception was thrown by the servlet after its output stream header was committed.

Category 2 — Message queue error

Table 3 shows the possible conditions for this error category.

Table 3. Category 2 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
12	1	`The message queue cannot be created.`	The message queue cannot be created.
4	1	`Timeout`	A timeout occurred when receiving a message from the message queue. MSG_QUEUE_PROTOCOL_ERROR_TIMEOUT
4	2	`Received unexpected msgType=nn`	Received unexpected message. MSG_QUEUE_PROTOCOL_ERROR_UNEXPECTED
4	3	`ServletDispatcher failed.`	Back-end ServletDispatcher failed with the reason <reason>, for example, TSO Prompt was received when TsoServletResponse was expected. MSG_QUEUE_PROTOCOL_ERROR_ENDED
4	4	`Queue full while sending.`	Message queue is full while sending the specific <message type>. MSG_QUEUE_PROTOCOL_ERROR_FULL
4	5	`Illegal state.`	The message queue is in an illegal state. MSG_QUEUE_PROTOCOL_ERROR_ILLEGAL_STATE
5	1	`Error parsing TsoServletResponse.`	Error occurred when paring TsoServletResponse. MSG_QUEUE_JSON_PARSE_ERROR
5	2	`Error serializing TsoServletRequest.`	Error occurred when serializing TsoServletRequest. MSG_QUEUE_JSON_SERIALIZE_ERROR
12	1	`The Message queue cannot be created.`	The message queue cannot be created.
12	2		Not used currently.
12	3	`Message queue size is less than minimum.`	Message queue size is less then the required minimum size. MSG_QUEUE_ERROR_SIZE_ERROR
12	4	`Message prefix bytes are too short.`	Message prefix bytes are shorter than expected. MSG_QUEUE_ERROR_DECODING
16	n(errno)	`Varies.`	This is an error from msgsnd()/msgrcv()/etc. The errno will be used as the reason. MSG_QUEUE_SYS_ERROR

Category 3 — Common event adapter (CEA) error

Table 4 shows the possible conditions for this error category.

Table 4. Category 3 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
12	1	`TSO launcher exception: Client is not authorized for instrumentation.`	The requestor lacks sufficient authority to access the requested common event adapter (CEA) service.
12	2	`TSO launcher exception: Error occurred.`	The requested CEA service encountered an error.
12	3	`TSO launcher exception: CEA address space is not available.`	The CEA address space is not active or is not available.
12	4	`TSO launcher exception: TSO address space cannot be created.`	The TSO/E address space cannot be created because a required system resource is not available.
12	5	`CeaTsoEnd request failed.`	An error occurred ending a TSO Address Space. CEA TSO Reason code = 4103. CEA_ERROR_END_TSO_FAILED
12	6		Not currently used. CEA_ERROR_CMD_NOT_FOUND

Category 4 — ISPF error

Table 5 shows the possible conditions for this error category.

Table 5. Category 4 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
n	m	varies	The return and reason code values match the return and reason code values that are set by the ISPF service.

Category 5 — Catalog Search Interface (CSI) error

Table 6 shows the possible conditions for this error category.

Table 6. Category 5 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
n	m	varies	The return and reason code values match the return and reason code values that are set by the consolidated software inventory (CSI) service.

Category 6 — Read or write error

Table 7 shows the return and reason codes that can be set for a read or write request.

Table 7. Category 6 errors for z/OS data set and file REST interface operations
rc	reason (hex)	message	Description
8	`201`	`<methodName> failed`	Unable to open a data set or member, `<methodName>` like fopen() or freopen() failed. RW_ERROR_OPEN_FAILED
8	`202`	`<methodName> failed`	Unable to close a data set or member,`<methodName>` like fclose() failed. If occurs for a write/put operation, the data set contents are not predictable. failedRW_ERROR_CLOSE_FAILED
8	`204`	`Client ETag does not match the current ETag for the data set.`	The attempt to write to the data set failed because the supplied ETag does not match the current ETag of the requested data set. This mismatch indicates that the data set content was modified in the time since the caller obtained the ETag. RW_ERROR_DS_ETAG_NOT_MATCHED
8	`208`	.`<methodName> error`	An error, `<methodName>` like fread(), occurred during I/O to a data set or Unix file. RW_ERROR_IO
8	`20C`	`Member not found.`	The member cannot be located in the partitioned data set. Perhaps the data set name or member name was incorrectly specified. RW_ERROR_MBR_NOT_FOUND
8	`0000020A`	`Dynamic allocation failed.`	This RC is combined with S99ERROR in the high halfword. RW_ERROR_DS_DYNALLOC_ERR
8	`1708020A`	`ISPF LMINIT - data set not found.`	The specified data set cannot be found. Perhaps the data set name or member name was incorrectly specified. RW_ERROR_DS_NOT_FOUND
8	`varies`	`Varies.`	For UNIX file I/O errors, the reason code consists of the errno in the high order 16 bits and the errno2 in the low order 16 bits.
8	`5E30062`	`File not found.`	The specified UNIX file cannot be found. Perhaps the data set name or member name was incorrectly specified. RW_ERROR_FS_NOT_FOUND
8	`5B6F0002`	`Client is not authorized for file access.`	The request for the UNIX file failed because the caller does not have sufficient authority to access the file. RW_ERROR_FS_AUTH
8	`406`	`Client ETag does not match the current ETag for the file.`	The attempt to write to the UNIX file failed because the supplied ETag does not match the current ETag of the requested file. This mismatch indicates that the file content was modified in the time since the caller obtained the ETag. RW_ERROR_FS_ETAG_NOT_MATCHED

Category 7 - JSON Parser Conditions

Category 7 JSON parser conditions shows the possible conditions for this error category.

Table 8. Category 7 JSON parser conditions
rc	reason	message	Description
n	m	`Varies.`	The rc and reason are set from the low level JSON Parser return code and reason code.

Category 8 - z/OS XL C/C++ Conditions

Category 8 z/OS XL C/C++ Conditions shows the possible conditions for this error category.

Table 9. Category 8 z/OS XL C/C++ Conditions
rc	reason	message	Description
n	m	`Varies.`	The rc and reason are set from the low level z/OS XL C/C++ return code and reason code.

Category 9 — Unexpected error

Table 10 shows the possible conditions for this error category.

Table 10. Category 9 errors for z/OS data set and file REST interface operations
rc	reason	message	Description
16	1	`Server error occurred.`	For details about the exception, see the stack property of the JSON error report document, which is described in Error report document.