Error reporting categories

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 that are produced or detected in the service layer.	Category 1 — Service error
Message queue	2	Errors that are produced or detected by the message queue.	Category 2 — Message queue error
CEA	3	Errors that are produced or detected by the common event adapter (CEA) interface.	Category 3 — Common event adapter (CEA) error
ISPF	4	Errors that are produced or detected by the Interactive System Productivity Facility (ISPF) interface.	Category 4 — ISPF error
CSI	5	Errors that are produced or detected by the catalog search interface (CSI).	Category 5 — Catalog Search Interface (CSI) error
Read or write function	6	Errors that are returned from an attempted read or write request.	Category 6 — Read or write error
JSON	7	Errors that are produced or detected when parsing JSON.	Category 7 — JSON Parser Conditions
XL C/C++	8	Errors that are produced or detected by z/OS XL C/C++	Category 8 — z/OS XL C/C++ Conditions
Unexpected	16	Unexpected errors detected.	Category 16 — 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. 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 or 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 cannot 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 cannot 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.
16	1	`Error occurred when connecting to remote server.`	An error occurred when the X-IBM®-Target-System header was set. See details to take action.

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
4	1	`Timeout`	Timeout occurred when receiving a message from the message queue. MSG_QUEUE_PROTOCOL_ERROR_TIMEOUT
4	2	`Received unexpected msgType=nn`	Unexpected message received. MSG_QUEUE_PROTOCOL_ERROR_UNEXPECTED
4	3	`ServletDispatcher failed.`	Back-end servlet dispatcher 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.`	Message queue is in an invalid 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.`	Message queue cannot be created.
12	2	Reserved.	Not used currently.
12	3	`Message queue size is less than minimum.`	Message queue size is less than 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.`	Error from msgsnd(), msgrcv(), or a related message queue service. The UNIX errno is the reason code. For reason code 1141, the following causes are possible: The TSO/E logon PROC is not correct. Ensure that the information specified on the RESTAPI_FILE statement in the IZUPRMxx parmlib member is correct. The user ID does not have a TSO segment in the RACF® user profile. TSO/E logon exit is active and is preventing the user ID from logging on. 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 requester 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
12	7	`Unable to find the system you requested`	CEA_ERROR_NO_TARGET_SYSTEM
12	n	`Error occurs while using remote CEA TSO address space services`	Refer to CEA TSO address space services reason code and diagnostic code for details.

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 this error occurs for a write or 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. If the message indicates a dynamic allocation error, then the rc is a decimal value and corresponds to a DYNALLOC reason code. For more information about the DYNALLOC reason code, see Interpreting error reason codes from DYNALLOC in z/OS MVS Programming: Authorized Assembler Services Guide.

Category 16 — 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, check the z/OSMF logs.