Register API error codes need to be aligned with the CDS standardised error codes

[CDR-API-Stream]

Description

The Register API error codes haven't been updated alongside the updates to the CDS error codes as conducted through DP 120 and documented in: https://consumerdatastandardsaustralia.github.io/standards/#error-codes. As a result of this, there is an inelegance where the current swagger definitions conflict with optional code usage. This negatively affects the usability of these APIs

An example of this is as follows:

Response codes for GetSSA:

Potentially conflicting error codes as defined in the CDS (note the MAY requirement)

Alignment to these error codes should be sought for completeness and to improve usability.

Area Affected

Register APIs

Change Proposed

Audit response codes and update alignment to the CDS error codes.

[CDR-API-Stream]

To address this issue, an audit has been performed on the register response error codes.

Proposal:

The following changes are proposed to ensure consistency between the CDS error codes and the Register API swagger definition.

The following represent the API associated error codes which will be added or updated:

API	Version	Updated Error Codes	New Error Codes
Get Data Holder Brands	V2	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Data Holder Brands Summary	V1	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field 404: Industry Not Found Invalid Industry
Get Software Statement Assertion (SSA)	V3	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field 403: Invalid BrandId The ADR or the ADR's Software Product is not active 404: Invalid Software Product Invalid Industry / Invalid Brand Id / Invalid Software Product Id
Get Data Holder Statuses	V1	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Software Products Statuses	V2	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Data Recipients Statuses	V2	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Data Recipients	V3	400: Missing Required Header / Invalid Version / Invalid Path Parameter Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry

These changes will only apply to the new Register API versions, with the dependency date of 15th November 2022.

Please refer to the Register Dependency Schedule for details.

---

One outstanding question is how the 422 error code defined in the Get Software Statement Assertion (SSA) V3 API should be specified. The ACCC will need to provide input as to whether the 422 error code is utilised and therefore should be specified in the CDR Register section of the error codes specification in the CDS, or, is redundant and therefore should be cleared up.

[perlboy]

Testing by both AEMO/ACCC for energy sector is scheduled to start in July. Will these changes be applied before, during or after industry testing has occurred?

[ACCC-CDR]

The ACCC requests that this issue be restricted to resolving documentation errors related to the usage of the CDR Register Errors of the CDS. While the ACCC supports the changes detailed above,we proposed that these should be revisited in a future maintenance iteration and implemented post the 15th November 2022.

The ACCC confirms that the 422 error code for the Get Software Statement Assertion (SSA) V3 API is superfluous and can be removed.

@perlboy the ACCC does not plan to conduct any specific energy sector testing with participants beyond the Conformance Test Suite. There are however tools available to assist energy participants with their build and test, including the Participant Tooling mock solutions and the soon-to-be-released CDR sandbox.

API	Version	Updated Error Codes	New Error Codes
Get Data Holder Brands	V2		404: Invalid Industry
Get Data Holder Statuses	V1		404: Invalid Industry
Get Software Statement Assertion (SSA)	V3	404: Invalid Software Product Invalid Industry / Invalid Brand / Invalid Software Product
Get Software Products Statuses	V2		404: Invalid Industry
Get Data Recipients Statuses	V2		404: Invalid Industry
Get Data Recipients	V3		404: Invalid Industry

[CDR-API-Stream]

Thanks @ACCC-CDR and @perlboy for your input.

Proposal

The DSB proposes to specify the appropriate error codes for the CDR Register APIs to align to the Standards error codes. These changes will be incorporated into future versions of the CDR Register APIs. Current versions will not be impacted.
 
The rationale for not incorporating this change into the current versions of the CDR Register APIs is due to the low priority of this change. The motivation for this change is to align the CDR Register APIs to the API conventions laid out in the Consumer Data Standards. These changes are low priority and will not be incorporated into V1.18.0, to minimise this implementation burden on participants.

The error codes to be adopted in a future version are:

API	Updated Error Codes	New Error Codes
Get Data Holder Brands	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Software Statement Assertion (SSA)	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field 403: The ADR or the ADR's Software Product is not active 404: Invalid Industry / Invalid Brand Id / Invalid Software Product Id
Get Data Holder Statuses	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Software Products Statuses	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Data Recipients Statuses	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry
Get Data Recipients	400: Missing Required Header / Invalid Header / Invalid Version / Invalid Field	404: Invalid Industry

Note that GetDataHolderBrandSummary is not specified as this API already aligns to the error code conventions

[CDR-API-Stream]

This issue has been staged at: ConsumerDataStandardsAustralia/standards-staging#202