Common request validation reason codes

Edit online

The Web Services API performs request validation on each request it receives to ensure the request is correctly formed and appropriate before it begins processing the request. Many errors of basic request syntax can occur on all or a large number of the operations provided by the API. Validation for these kinds of errors is done in a common way across all of the operations and results in a common (not request-specific) reason code being reported if errors are detected. Other validation is operation-specific by nature, and results in operation-specific reason codes when errors are detected.

The following table provides the HTTP status codes and reason codes for common request validation. These status and reason codes may be reported on any of the operations of the API.

HTTP status code	Reason code	Description
400 (Bad Request)	1	The request included an unrecognized or unsupported query parameter.
	2	A required request header is missing or invalid.
	3	A required request body is missing.
	4	A request body was specified when not expected.
	5	A required request body field is missing.
	6	The request body contains an unrecognized field (i.e. one that is not listed as either required or optional in the specification for the request body format for the operation).
	7	The data type of a field in the request body is not as expected, or its value is not in the range permitted.
	8	The value of a field does not provide a unique value for the corresponding data model property as required.
	9	The request body is not a well-formed JSON document.
	11	The length of the supplied request body does not match the value specified in the Content-Length header.
	13	The maximum number of logged in user sessions for this user ID has been reached; no more are allowed.
	14	Query parameters on the request are malformed or specify a value that is invalid for this operation. Common causes include the inability to successfully decode a parameter element, the presented parameters are not in the expected key=value format, the value is not a valid regular expression, a required parameter is missing, multiple instances of a parameter are present on an operation that does not permit multiple instances of that parameter, or the value is not a valid enum for the operation.
	15	The request body contains a field whose presence or value is inconsistent with the presence or value of another field in the request body. A prerequisite condition or dependency among request body fields is not met.
	18	The request body contains a field whose presence or value is inconsistent with the type of the object. Such a requirement is often described in an object's data model as the field having a prerequisite condition on a "type", "family", or similar property that identifies an object as being of a particular type. Such a property is typically, but not necessarily, immutable.
	19	The request body contains a field whose corresponding data model property is no longer writable. In certain earlier HMC and/or SE versions the property is writable, but later versions do not allow changing the property through the Web Services APIs. This could be due to a change in the underlying system-management model, or the property may have become obsolete.
	20	The request body contains a field or value that is directly or indirectly dependent on the version of the SE that is targeted by or associated with the request operation, and that SE is not at a version that supports or provides the field or value.
	21	There was an error decoding either the URI, method, header, or body for a request received over the BCPii interface.
	4000¹	A non-null address was provided for the request body data area but the length passed in for the area was 0.
	4001¹	The length provided for the request body data area exceeded the supported 64KB.
	4002¹	The request body encoding is not the expected UTF-8.
	4003¹	The request body encoding is not the expected IBM-1047.
	4004¹	The request body contains malformed JSON. See the message, in the error response body, for further information.
	4005¹	The address provided for the required URI data area is null.
	4006¹	A non-null address was provided for the URI data area but the length passed in for the area was 0.
	4007¹	The length provided for the URI data area exceeded the supported 2048 bytes.
	4008¹	The contents of the URI data area evaluated to an empty string. A valid, non-empty string, is required for the URI.
	4009¹	A non-null address was provided for the target name data area but the length passed in for the area was 0.
	4010¹	The length provided for the target name data area exceeded the supported 256 bytes.
	4011¹	A non-null address was provided for the client correlator data area but the length passed in for the data area was 0.
	4012¹	The length provided for the client correlator exceeded the supported 64 bytes.
	4013¹	A null address was provided for the required response body data area. A valid address to a data area, minimum 500 bytes, is required.
	4014¹	A non-null address was provided for the response body data area but the length of the data area did not meet the minimum 500 bytes requirement.
	4015¹	The encoding parameter contained an unrecognized value. See the IDF corresponding to the programming language for valid encoding constants.
	4016¹	The HTTP method parameter contained an unrecognized value. See the IDF corresponding to the programming language for valid HTTP method constants.
	4017¹	The length of the response date data area is not the required 29 bytes.
	4018¹	The length of the request ID data area is not the required 64 bytes.
	4019¹	The length of the location data area is not the required 2048 bytes.
	4020¹	The URI contains an unrecognized value.
	4021¹	The target name contains an unrecognized value.
	4022¹	The data area associated with the URI is not accessible by BCPii.
	4023¹	The data area associated with the request body is not accessible by BCPii.
	4024¹	The data area associated with the target name is not accessible by BCPii.
	4025¹	The data area associated with the client correlator is not accessible by BCPii.
	4026¹	The data area associated with the response date is not accessible by BCPii.
	4027¹	The data area associated with the request ID is not accessible by BCPii.
	4028¹	The data area associated with the location is not accessible by BCPii.
	4029¹	The data area associated with the response body is not accessible by BCPii.
	4030¹	The data area associated with the request parameter is not accessible by BCPii.
	4031¹	The calling program resides in an unsupported environment.
	4032¹	The calling program is disabled.
	4033¹	The calling program is holding one or more locks.
	4034¹	The calling program is not in task mode.
	4035¹	The request is not supported for this type of REXX environment.
	4036¹	A valid target name is required for this type of request, however the target name value was either not provided or evaluated to an empty string.
	4300¹	The calling REXX program did not provide the required URI.
	4301¹	The calling REXX program did not provide the required HTTP method.
	4302¹	The calling REXX program provided a URI that was not a valid string.
	4303¹	The calling REXX program provided a bad HTTP method value.
	4304¹	The calling REXX program provided a target name that was not a valid string.
	4305¹	The calling REXX program provided a client correlator that was not a valid string.
	4306¹	The calling REXX program provided a request body that was not a valid string.
	4307¹	The calling REXX program provided a bad encoding value.
	4308¹	The calling REXX program provided a timeout value that was not a valid integer.
403 (Forbidden)	1	The user under which the API request was authenticated does not have the required authority to perform the requested action.
	4	The request requires authentication but no X-API-Session header was specified in the request.
	5	An X-API-Session header was provided but the session id specified in that header is not valid.
	301	The operation cannot be performed because it targets a CPC that does not support Web Services API operations.
	4000¹	The user ID associated with the calling program is either lacking authority to use BCPii or to the particular resource associated with the request. For details regarding authority to BCPii, refer to https://www.ibm.com/docs/en/zos/2.4.0?topic=bcpii-general-security-product-authority. For details regarding authority to issue the request, see Base Control Program internal interface (BCPii).
	4001¹	The calling program is running in a problem state, PKM8-15, and is not executing from an APF-authorized library.
	4002¹	The calling REXX program is running in a problem state, PKM8-15, and is not executing from an APF-authorized library.
404 (Not Found)	1	The request URI does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission. For URIs that contain object ID and/or element ID components, this reason code may be used for issues accessing the resource identified by the first (leftmost) such ID in the URI.
	2	A URI in the request body does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission. For URIs that contain object ID and/or element ID components, this reason code may be used for issues accessing the resource identified by the first (leftmost) such ID in the URI.
	4	The object designated by the request URI does not support the requested operation.
	5	The request URI does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission. More specifically, this reason code indicates issues accessing the resource identified by the element ID component in the URI. Such an element ID is typically the second (counting left to right) ID component in the URI.
	6	A URI in the request body does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission. More specifically this reason code indicates issues accessing the resource identified by the element ID component in the URI. Such an element ID is typically the second (counting left to right) ID component in the URI.
	7	The identified Server-Sent Events stream or BCPii Registration ID was not found. [Added by feature bcpii-notifications]
409 (Conflict)	1	The operation cannot be performed because the object designated by the request URI is not in the correct state.
	2	The operation cannot be performed because the object designated by the request URI is currently busy performing some other operation.
	3	The operation cannot be performed because the object designated by the request URI is currently locked to prevent disruptive changes from being made.
	4	The operation cannot be performed because the CPC designated by the request URI is currently enabled for DPM.
	5	The operation cannot be performed because the CPC designated by the request URI is currently not enabled for DPM.
	6	The operation cannot be performed because the object hosting the object designated by the request URI is not in the correct state.
	8	The operation cannot be performed because the request would result in the object being placed into a state that is inconsistent with its data model or other requirements. The request body contains a field whose presence or value is inconsistent with the current state of the object or some aspect of the system, and thus a prerequisite condition or dependency would no longer be met.
	9	The operation cannot be completed because it is attempting to update an effective property when the object is not in a state in which effective properties are applicable. More specifically, the request body contains one or more fields which correspond to a property marked with the (e) qualifier in the data model, and the object's effective-properties-apply property is false.
	10	The operation cannot be performed because the affected SE is in the process of being shut down.
	11	The operation cannot be performed because it requires a fully authenticated session and the API session that issued it is only partially authenticated.
	12	The operation cannot be performed because a firmware feature that prohibits the operation is currently enabled. The error-details field of the response body contains an error-feature-info object identifying the firmware feature whose current enablement status is invalid for the operation. The error-feature-info object is described in the next table.
	13	The operation cannot be performed because a firmware feature required by the operation is currently disabled. The error-details field of the response body contains an error-feature-info object identifying the firmware feature whose current enablement status is invalid for the operation. The error-feature-info object is described in the next table.
	14	The operation cannot be performed because the data that would be changed is currently subject to Data Replication from a PRIMARY or PEER HMC. When the HMC is a Data Replication REPLICA any data that is subject to replication cannot be changed.
	15¹	The response content cannot be returned to the BCPii client application because the data area provided for the response body is not large enough to contain it. [Added by feature rc-409-15]
¹This reason code is only applicable to operations initiated through the BCPii interface.

The error-feature-info object contains the following fields:

Table 1. error-feature-info object properties
Field name	Type	Description
scope	String Enum	The scope of the firmware feature requirement. The valid values are: "cpc" - The firmware feature enablement requirement applies to the CPC object involved in the operation. "partition" - The firmware feature enablement requirement applies to the Partition object involved in the operation.
name	String Enum	The name of the firmware feature requirement. When the scope is "cpc", this is a firmware feature name from the CPC's available-features-list property. When the scope is "partition", this is a firmware feature name from the Partition's available-features-list property.