Software management services

For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. Some errors might also include a returned JSON object that contains the following attributes:

{
  "error":
  {
    "reason":"reason-code",
    "messages":["message-text"],
    "stack":"stack-trace"
  }
}

where:

error

JSON object that contains a reason code, a list of one or more message strings to describe the errors detected while processing the request, and for some errors, a stack trace of the exception.

reason-code

Reason code returned for the request. The value is an integer.

message-text

Array that contains the text of each message that was issued.

stack-trace

Stack trace for the exception.

The following HTTP status codes are valid:

HTTP 200 OK

Success.

HTTP 400 Bad request

The request contained incorrect parameters. Table 2 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 400, and provides a brief description of the error.

Table 2. Reason codes and messages returned for HTTP response code 400

Reason Code	Message	Description
4	The required attribute attribute-name is missing. Add the missing attribute and retry the request.	The input JSON object is missing a required attribute.
5	The object-type name object-name is not valid. Specify a valid name and retry the request.	A software instance or category name specified in the input JSON object is not valid.
6	The global zone CSI data set name CSI-data-set-name is not valid. Specify a valid CSI data set name and retry the request.	The CSI data set name specified in the input JSON object is not valid.
7	SMP/E zone name zone-name is not valid. Specify a valid target zone name and retry the request.	A target zone name specified in the input JSON object is not valid.
8	The description cannot exceed 256 characters. Specify a valid description and retry the request.	The description specified in the input JSON object exceeds the maximum length.
9	Data set name data-set-name is not valid. Specify a valid data set name and retry the request.	A non-SMP/E managed data set name specified in the input JSON object is not valid.
10	Data set volume volume-serial is not valid. Specify a valid volume serial and retry the request.	A data set volume specified for a non-SMP/E managed data set in the input JSON object is not valid.
13	Category name category-name is a reserved category name. Specify a category name that is not reserved and retry the request.	A category named "NOCATEGORY" was specified in the input JSON object, which is not allowed.
41	The request cannot be performed because the software instance does not have a global zone.	Products, features, and FMIDs cannot be loaded for the subject software instance because the software instance does not have a global zone property.
42	Both of the properties {0} and {1} are missing, but one is required. Add one or both of the missing properties and retry the request.	Every software instance must have at least one of the specified properties. Either add one or both of the missing properties and retry the request.
43	The {0} property requires the {1}property, but the {1} property is missing. Either add the {1} property or remove the {0} property and retry the request.	For every software instance, the first identified property can only be specified if the second identified property is also specified. Either add the second property or remove the first, and retry the request.
45	The package directory {0} is not valid. Specify a valid UNIX directory path and retry the request.	The package directory specified in the input JSON is invalid.
46	The JCL data set name {0} is not valid. Specify a valid data set name and retry the request.	The JCL data set name specified in the input JSON is invalid.
47	JCL card {0} for the JOB statement is not valid. Specify a valid JOB statement and retry the request.	The JOB statement specified in the input JSON is invalid.
48	The UNIX file system data set name{0} is not valid. Specify a valid dataset name and retry the request.	A data set name for a UNIX file system data set in the input JSON is invalid.
49	The UNIX file system mount point {0}for data set {1} is not valid. Specify a valid UNIX path and retry the request.	A mount point for a UNIX file system dataset in the input JSON is invalid.
50	JCL data set {0} is not valid. It must be a PDS or PDS/E with a fixed block record format and a logical record length of 80.	The JCL data set specified in the input JSON exists but has incorrect attributes.

HTTP 401 Unauthorized

The submitter of the request did not authenticate to z/OSMF.

HTTP 403 Forbidden

The server rejected the request. Table 3 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 403, and provides a brief description of the error.

Table 3. Reason codes and messages returned for HTTP response code 403

Reason Code	Message	Description
1	User user-ID is not authorized to use the task-name task on system system-name.	The specified user is not authorized to use the Software Management task on the indicated system.
11	The software instance cannot be action-requested because category category-name does not exist and user user-ID is not authorized to add categories.	The request to add or update (action-requested) the software instance failed because the categories indicated in the message do not exist and the z/OSMF user is not authorized to add categories.
12	The software instance cannot be action-requested because user user-ID is required to specify one or more categories.	The request to add or update (action-requested) the software instance failed because the software instance is not assigned to a category and the z/OSMF user is not authorized to define uncategorized software instances.
14	The action on the software instance cannot be performed because user user-ID is not authorized to use category category-name.	The z/OSMF user is not authorized to read the specified category.
15	The software instance cannot be action-requested because category category-name does not exist and user user-ID is not authorized to add the category.	The request to add or update (action-requested) the software instance failed because the specified category does not exist and the z/OSMF user is not authorized to add the category.
17	The software instance cannot be action-requested because global zone CSI-data-set-name on system system-name does not exist and user user-ID is not authorized to add the global zone.	The request to add or update (action-requested) the software instance failed because the specified global zone does not exist and the z/OSMF user is not authorized to add the global zone.
18	User user-ID is not authorized to perform the requested action on software instance instance-name on system system-name.	The z/OSMF user is not authorized to perform the requested action on the specified software instance.
35	User user-ID is not allowed to obtain the results for this request. Only user submitter-user-ID, who submitted the request, is allowed to obtain the results.	When an asynchronous operation is requested, z/OSMF ensures that the user ID that submits the request is authorized to perform the operation. Because authorization checking is not performed when the results are obtained, only the user ID that submitted the request is allowed to obtain its results.

HTTP 404 Not found

The target of the request was not found. Table 4 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 404, and provides a brief description of the error.

Table 4. Reason codes and messages returned for HTTP response code 404

Reason Code	Message	Description
19	System entry system-name is not defined to z/OSMF. Specify the name for an existing z/OSMF system entry and retry the request.	A system entry was not found in the z/OSMF Systems task for the system name specified in the input JSON object.
21	A software instance with the name instance-name on system system-name does not exist. Specify an existing software instance and retry the request.	The software instance does not exist.
40	The results for the request have expired and are no longer available, or no such request exists.	The service could not find any results for the request identified on the status URL because either the ID specified in the URL is incorrect or the time period for which z/OSMF keeps the results has elapsed, causing the results to expire and be unavailable for the client to obtain.

HTTP 409 Conflict

The request could not be completed because there is a conflict with the current state of the resource. Table 5 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 409, and provides a brief description of the error.

Table 5. Reason codes and messages returned for HTTP response code 409

Reason Code	Message	Description
20	The software instance cannot be action-requested because a software instance with the name instance-name on system system-name already exists.	The request to add or update (action-requested) the software instance failed because a software instance with the specified name already exists on the specified system. The software instance name and system combination must be unique.
23	The software instance cannot be {added|updated|exported} because it is being deployed or replaced in a deployment that is in progress.	The software instance cannot be updated,deleted or exported because it is being deployed or replaced in a deployment that is in process. You must cancel the in-process deployment before updating,deleting or exporting the software instance.
24	The software instance cannot be {updated|deleted|exported} because it is currently locked by user user-ID. It was locked at date-time.	A software instance cannot be updated,deleted, or exported while it is currently locked and being updated by another user. The date and time when it was locked is given. The software instance must be unlocked before attempting to update,delete or export it.
52	The software instance cannot be exported because user {0} is exporting the same software instance and has stolen the lock. Try the request again later.	A software instance cannot be exported while it is being exported by another user. The current export operation must complete before attempting to export the software instance again.

HTTP 500 Internal server error

The server encountered an error that prevented it from completing the request. Table 6 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 500, and provides a brief description of the error.

Table 6. Reason codes and messages returned for HTTP response code 500

Reason Code	Message	Description
2	The request could not be completed because an error occurred. Error: error-details	An unexpected error occurred while processing the request. The details of the error (error-details) are provided in the message.
22	The maximum number of products, features, and FMIDs that can be returned for a software instance was exceeded.	More than 10,000 products, features, and FMIDs exist for the specified software instance; however, only 10,000 or fewer can be returned.
25	The request failed because system entry system-name is not defined to z/OSMF.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the specified system does not exist in the z/OSMF Systems task. Define the system to the primary z/OSMF instance, and retry the request.
26	A secure connection to z/OSMF host system system-name could not be established because the certificate for the specified system is not trusted or has changed.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the certificate for the secondary z/OSMF instance is not trusted or has changed.
27	A secure connection to z/OSMF host system system-name could not be established because an error occurred. Error: error-details	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because an error occurred. Additional information about the error is provided in the message text.
28	The attempt to connect to z/OSMF host system system-name failed, perhaps due to a momentary loss of connectivity. If this error persists, however, a more serious connectivity problem might exist in your network.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because a connectivity error occurred. Try the request again later.
29	The request was not completed because the connection to z/OSMF host system system-name timed out.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the connection to that system timed out.
30	The attempt to authenticate with z/OSMF host system system-name failed because the security credentials provided are not valid.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the user ID and password or passphrase specified for the secondary z/OSMF instance in the input JSON object are not valid. Specify the correct user ID and password or passphrase, and retry the request.
31	The attempt to connect to z/OSMF host system system-name failed because the security credentials provided for proxy server proxy-name are not valid.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the user ID and password specified for the HTTP proxy server in the input JSON object are not valid. Specify the correct user ID and password, and retry the request.
32	The attempt to authenticate with z/OSMF host system system-name failed because security credentials are required, but none were provided.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the user ID and password for the secondary z/OSMF instance were not specified in the input JSON object. Specify the correct user ID and password, and retry the request.
33	The attempt to connect to z/OSMF host system system-name failed because security credentials for proxy server proxy-name are required, but none were provided.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because the user ID and password for the HTTP proxy server were not specified in the input JSON object. Specify the correct user ID and password, and retry the request.
34	A connection to z/OSMF host system system-name could not be established because an error occurred. See the z/OSMF logs for additional details on the cause of the error.	The primary z/OSMF instance cannot connect to the secondary z/OSMF instance that resides in the same sysplex as the software instance because an error occurred. Examine the z/OSMF logs to obtain more information about the cause of this problem.
36	SMP/E-messages	The request could not be completed because one or more errors were detected by SMP/E. The messages returned from SMP/E are provided. Resolve any errors, and retry the request.
37	The product, feature, and FMID information was not loaded because the software instance was recently modified. Try the request again.	The software instance was modified by another user while the retrieve product, feature, and FMID information request for the software instance was in progress. The results of the retrieve operation cannot be trusted and have been discarded. Try the request again after the modify operation is completed.
38	z/OSMF on system system-name is not at the required service level to communicate with a higher level of z/OSMF on other systems. z/OSMF FMID fmid on system system-name requires APAR apar-number.	The requested action requires that z/OSMF communicate with instances of z/OSMF on other systems. However, the z/OSMF instance on the indicated system is not at a service level that supports communicating with higher levels of z/OSMF on other systems. The FMID for the z/OSMF plug-in that requires service is indicated in the message. To allow communication between the z/OSMF instances, ensure that the z/OSMF instances are at compatible service levels. To do so, install the PTF for the indicated APAR onto the indicated system.
39	z/OSMF FMID fmid on system system-name is not at the required software level to communicate with a higher level of z/OSMF on other systems.	The requested action requires that z/OSMF communicate with instances of z/OSMF on other systems. However, the z/OSMF instance on the indicated system is not at a release level that supports communicating with higher levels of z/OSMF on other systems. The FMID for the z/OSMF plug-in that requires a software update is indicated in the message. To allow communication between the z/OSMF instances, ensure that the z/OSMF instances are at compatible software levels. To do so, upgrade the release of z/OSMF on the indicated system.
51	An I/O exception occurred: {0}	The request could not be completed because an I/O error exception has occurred. Details about the error are provided.

HTTP 503 Service unavailable

The server is currently unavailable to process the request. Table 7 lists the reason codes and messages that can be included in the JSON object returned with HTTP response code 503, and provides a brief description of the error.

Table 7. Reason codes and messages returned for HTTP response code 503

Reason Code	Message	Description
3	z/OSMF is unable to process your request because z/OSMF is busy processing similar requests for other users. Try the request again later.	Multiple users are attempting to access the same database tables and are waiting for each other's transaction to complete, causing a database deadlock condition to occur.