Decision Proposal 156 - Enhanced Error Handling: Custom Error Code Discovery Service

[CDR-API-Stream]

This decision captures the outcome of the Enhanced Error Handling consultation. The Data Standards Chair approved the changes to be made. The decision record is available here: Decision 154-155-156 - Enhanced Error Handling - Summary of Changes To Be Made.pdf

These changes will be incorporated into release v1.10.0 of the Consumer Data Standards

---

This issue pertains to the consultation for Enhanced Error Handling.

Specifically, this decision proposal is seeking to address how participants — particularly ADRs — may discover custom error codes not covered by the standardised error code catalogue are used by servers where commercial / voluntary extensions to the core CDR APIs are offered.

The consultation draft Decision Proposal has been attached below:
Decision Proposal 156 - Enhanced Error Handling - Error Code Discovery Service.pdf

Feedback is now open for this proposal. Feedback is planned to be closed on 19th February 2021.

[CDR-API-Stream]

Related Decision Proposals open for feedback:

• Decision Proposal 154 - Enhanced Error Handling: Error Code Payload Structure and Transition Arrangements #154
• Decision Proposal 155 - Enhanced Error Handling: Error Code Catalogue #155

[NationalAustraliaBank]

NAB supports Option A as it allows DH's to implement industry best practice. This includes:

• Common error codes documented in a developer-friendly manner
• Custom error codes provided in each specific API specification

With Option B, maintaining the error codes in two places (ie. specific APIs on Developer Portal as well as in a separate JSON file) presents a risk that the data will get out of sync. We also believe that Option B would make it difficult for recipient developers to interpret the errors because the JSON file is not "human readable". 

NAB believes this creates unreasonable overhead / duplication of work for DH and recipients and that there is more value in documenting the specific error handling within the API instead of providing all the error codes in one big JSON file.

[commbankoss]

Commonwealth Bank has the following feedback on this decision proposal:

• While we don't oppose option B: Discovery Service Via Developer Portal, we recommend this issue be considered in conjunction with decision proposal 158. It may be useful to include proprietary errors in the participant capability discovery mechanism instead.
• Q1: As above, we recommend considering hosting this alongside other categories mentioned in proposal 158.
• Q5: These may change in response to defects or to changes in DH implementation. Once the ecosystem has matured more, these will likely update due to CDR requirements changes.
• Q6: As long as this isn't mandatory, we have no issue with participants including future dated error codes.
• Q7: Versioning the data would be beneficial, for example for mapping errors between versions.

[anzbankau]

We are supportive of the approach and mechanism for handling custom error codes. We would like clarity provided on whether a data holder without any custom error codes needs to provide this data. Our preference would be for this to not be mandated in such a scenario.

We also agree with NAB that depending on how the Data Holder is managing their developer portal there may be duplication. Perhaps the requirement to publish error codes within the standardised JSON file could only be if they are not otherwise suitably covered by existing documentation in the developer portal.  

In response to the questions raised in the proposal:

• (Question 1) ANZ recommends this should be on developer portal as opposed to introducing a new end point. This is line with previous feedback to earlier proposals.
• (Question 2) ANZ doesn’t recommend including additional information as it is beyond the scope of error handling discovery mechanism.
• (Question 3) ANZ doesn’t recommend this should be made mandatory. I.e. if a participant doesn’t have custom error codes they shouldn't need to provide this
• (Question 4) ANZ would anticipate changes to custom error codes would be on a infrequent / ad-hoc basis.
• (Question 5) ANZ believe that a requirement to advertise the new errors in advance would be positive introduction, however the lead times should not be stipulated to allow for varying release schedules amongst participates.

On the timing of these error handling decision proposals we do have concerns due to the the large amount of scope currently targeting the November release. We recommend an appropriate time would be February 2022.

[PratibhaOrigin]

Feedback from Origin Energy on DP-156

From our review of DP 154, 155 & 156 , it appears these papers will be still bit focussed on Banking sector at this stage. However, we have reviewed the paper from energy sector perspective and generic architecture & design preference.

• Decision on Mandatory error discovery service: Option A no mandatory service will be preferred to avoid additional development. If the error structure well defined will full title, description & status then purpose of discovery service could be diminish.
• In terms of data hosting, an API based service will be preferred.
• For the participants to reliably discover the location of the data , there should be a standard path across all DHs domains. Eg. /cdr/error-codes.
• Origin prefers the versioning of the data.
• Implementation section is not relevant for energy sector.

[ryderwj]

Option A is supported. 

The existence of a standard error catalog reducing the incidence of custom error codes, combined with the practicalities of ADRs consuming catalogs from hundreds of data holders suggests that the investment in a mandated approach may not be effective .  An optional approach using the standard representation in this proposal can be applied in the cases of custom extensions or on a voluntary basis.

[WestpacOpenBanking]

Westpac believes that the data standards should be developed to the extent needed to avoid point to point implementation by participants. In particular distinct error codes should be published as part of the data standards (as per DP155) where required to support a customer experience outcome and Option A should be adopted.

We are not supportive of Option B because it imposes significant burden in creating and maintaining exhaustive documentation of error codes with no customer experience benefit under the recommendations above. We note that participants may be incentivised to genericize errors if this approach is adopted.

[CDR-API-Stream]

Thank you to everyone who's put forward feedback. Consultation has been closed and feedback will now be reviewed and considered.

[CDR-API-Stream]

Thank you to everyone who provided feedback. The general consensus from participants is that mandatory format should not be imposed on how error codes are represented on CDR developer portals. Instead, participants should be allowed to publish custom error codes on their developer portals in the format of their choice without the need for standards.

Where participants do rely on custom error codes, the feedback supported that those participants MUST publish them on their developer portal. This would also include existing data holders who will require a transition from any existing error codes towards the standardised CDR error codes. If the DH does not use any custom error codes beyond what the CDS defines, then this requirement would not apply.

Recommendation

• ADRs and DHs MUST document custom error codes in a developer-friendly manner
• The format is at the discretion of the participant and they MAY use the schema provided or the format supported by the Dev Portal

DSB Commentary

• This seems a reasonable approach as most scenarios where custom extensions (e.g. competitive APIs) will occur also coincide with a high motivation for well-documented API specifications.
• However, the DSB will monitor how data holders implement custom error codes not covered by the CDS. If it is deemed that more proscriptive guidance and standards are required, this will be enforced.

[CDR-API-Stream]

Hi @NationalAustraliaBank, thanks for the feedback.

NAB supports Option A as it allows DH's to implement industry best practice. This includes:
Common error codes documented in a developer-friendly manner
Custom error codes provided in each specific API specification

This has been the general consensus and it is the recommended approach.

With Option B, maintaining the error codes in two places (ie. specific APIs on Developer Portal as well as in a separate JSON file) presents a risk that the data will get out of sync. We also believe that Option B would make it difficult for recipient developers to interpret the errors because the JSON file is not "human readable".

It's expected that participants publishing their APIs are likely to provide a human readable format and machine readable format. Based on the feedback we've received it has been suggested that this be left to the discretion of the participants based on their developer portal technology and approach. This is a pragmatic approach and participants would still be expected to publish custom error codes albeit aligned to their developer portal processes.

[CDR-API-Stream]

Hi @commbankoss, thanks for the feedback.

While we don't oppose option B: Discovery Service Via Developer Portal, we recommend this issue be considered in conjunction with decision proposal 158. It may be useful to include proprietary errors in the participant capability discovery mechanism instead.
Q1: As above, we recommend considering hosting this alongside other categories mentioned in proposal 158.

This may be a good approach where DHs can publish a URL to their developer portals. Publishing a list of error codes within the discovery response isn't anticipated.

Q7: Versioning the data would be beneficial, for example for mapping errors between versions.

Because Option B is not supported this will be left to the discretion of the participant.

[CDR-API-Stream]

Hi @anzbankau, thanks for the feedback.

We are supportive of the approach and mechanism for handling custom error codes. We would like clarity provided on whether a data holder without any custom error codes needs to provide this data. Our preference would be for this to not be mandated in such a scenario.
We also agree with NAB that depending on how the Data Holder is managing their developer portal there may be duplication. Perhaps the requirement to publish error codes within the standardised JSON file could only be if they are not otherwise suitably covered by existing documentation in the developer portal.

Where DHs don't use any custom error codes to extend their interface contract with ADRs then this would not apply to them. The purpose is to ensure participants have a reliable way to develop client software where error responses differ to the standardised list of CDR error codes.

In response to the questions raised in the proposal:
(Question 5) ANZ believe that a requirement to advertise the new errors in advance would be positive introduction, however the lead times should not be stipulated to allow for varying release schedules amongst participates.

This would at the discretion of the participant and it is anticipated that DHs would be incentivised to ensure ADRs can reliably integrate with their DH solutions, especially where there DH supports extensions to the mandatory set of CDR APIs.

On the timing of these error handling decision proposals we do have concerns due to the the large amount of scope currently targeting the November release. We recommend an appropriate time would be February 2022.

Thank you this has been taken into consideration in feedback to DP 154.

[CDR-API-Stream]

Hi @PratibhaOrigin, thanks for the feedback.

From our review of DP 154, 155 & 156 , it appears these papers will be still bit focussed on Banking sector at this stage. However, we have reviewed the paper from energy sector perspective and generic architecture & design preference.

Although a number of error codes have been informed through the implementation of the CDR in banking, a sector agnostic approach has been taken to make this applicable across sectors beyond banking.

For the participants to reliably discover the location of the data , there should be a standard path across all DHs domains. Eg. /cdr/error-codes.

As @commbankoss points out, this may be better achieved through the discovery mechanisms consulted on under DP 158. Because no mandatory error catalogue is recommended, having a known path to any list of errors would not be required.

Origin prefers the versioning of the data.

DHs may version data according to their approach for documenting CDR APIs on their developer portals.

[CDR-API-Stream]

Hi @ryderwj, thanks for the feedback.

Option A is supported.
The existence of a standard error catalog reducing the incidence of custom error codes, combined with the practicalities of ADRs consuming catalogs from hundreds of data holders suggests that the investment in a mandated approach may not be effective . An optional approach using the standard representation in this proposal can be applied in the cases of custom extensions or on a voluntary basis.

This aligns to the feedback received by other participants. The format will not be defined however DHs that support custom error codes are expected to publish them in a developer friendly way that is discoverable by ADRs.

[CDR-API-Stream]

Hi @WestpacOpenBanking, thanks for the feedback.

Westpac believes that the data standards should be developed to the extent needed to avoid point to point implementation by participants. In particular distinct error codes should be published as part of the data standards (as per DP155) where required to support a customer experience outcome and Option A should be adopted.

One of the underlying design principles of the data standards is to allow DHs to extend the CDR APIs. It is expected that custom error codes will continue to play an important role where DHs offer commercial extensions to the binding CDR APIs. For binding CDR APIs, we agree that the reliance of custom error codes is reduced significantly through the introduction of a standard set of CDR error codes.

[CDR-API-Stream]

The changes related to these consultations have now been staged in draft format. They are available for review here: ConsumerDataStandardsAustralia/standards-staging@release/1.10.0...dp/154

At this time, the changes are not formal data standards. A formal decision will be taken to the Data Standards Chair next week. Where reviewers identify issues with presentation, please raise a change request on Standards Maintenance so the DSB can address.

A draft version of the generated standards documentation is viewable here: http://ec2-18-224-29-97.us-east-2.compute.amazonaws.com

[CDR-API-Stream]

The Data Standards Chair approved the changes to be made. The decision record is available here: Decision 154-155-156 - Enhanced Error Handling - Summary of Changes To Be Made.pdf

These changes will be incorporated into release v1.10.0 of the Consumer Data Standards

[CDR-API-Stream]

These changes have now been incorporated into v1.10.0. Accordingly, this decision is closed.