Decision Proposal 154 - Enhanced Error Handling: Error Code Payload Structure and Transition Arrangements

[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 the list of transition arrangements and payload changes to support standardised error codes across the CDR ecosystem.

The consultation draft Decision Proposal has been attached below:
Decision Proposal 154 - Enhanced Error Handling - CDR Error Code Payload Structure and Transition Arrangements.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 155 - Enhanced Error Handling: Error Code Catalogue #155
• Decision Proposal 156 - Enhanced Error Handling: Custom Error Code Discovery Service #156

[spikejump]

Intuit welcomes the opportunity to provide feedback on DP154.

Option A2: We are supportive of it.

Option B1: We are supportive of it. However, can we please get clarification on how the old/custom and new code will co-exist? We are assuming the new code/title will appear in new payload structure. The old/custom code/title will appear in the “meta” block? In addition, what if DHs want to modify their “old” code to a new custom code at the same time? The existing “meta” structure does not cater for multiple custom data. Should the old be presented in a meta/v1 block and let meta to contain new custom code if it exists? or DHs are prohibited from changing old code/title to a new custom code/title?

Can we please also request extension of this option in that with any change of error codes/titles, the DHs are required to provide a documented mapping in their online developer portal? This, in essence, is no different than documenting release changes. The rationale here is ADRs can’t be waiting for an error to occur to organically accommodate the change. E.g. if an error is not encountered by ADR just before Feb 2022 it will be too late for ADRs to respond in a compliant fashion.

Option C2: Error responses are really no different than “success” responses. They are all part of the API contract that needs to be upheld. If there’s a change to the contract then the client side needs to be aware and process accordingly. For this reason, we are not supportive of option C2 on its own. Instead, we are supportive of option C3 where version negotiation with custom headers such as x-cds-accept-error-version: v2 should be accommodated. However, if B1 is to go ahead then C2 should workout.

Obligation Date: We would recommend a deprecation of old error code(s)/title(s) 12-month after new code(s)/titles) are introduced. The rational is to provide adequate time for ADRs to discover change organically and plan for its upgrade. Bear in mind without proper documentation from DHs, ADRs can only discover error change when they occur.

[WestpacOpenBanking]

Our interpretation of the proposed transition arrangements as described in Option B1 under Payload structure option A2 is that old and new error codes during transition would be provided as separate objects in the error object as per the following example:

Pre-transition:

{
    “errors”:
    [
        {
            “code”: “existing error code”
            “title”: “Existing error message”
            “status”: 406
        },
    }
}

During transition period:

{
    “errors”:
    [
        {
            “code”: “urn:au-cds:error:cdr-all:Header/InvalidVersion”
            “title”: “Version 5 was supplied but Get Product Detail only supports x-min-v = 2, x-v = 3”
            “status”: 406,
            “meta”: {
                “xStatus”: “400”,
                “xCode”: “ERR_406”,
                “xTitle”: “Version 5 is Not Acceptable”,
           }
        },
        {
            “code”: “existing error code”
            “title”: “Existing error message”
            “status”: 406
        },
    }
}

Post transition:

{
    “errors”:
    [
        {
            “code”: “urn:au-cds:error:cdr-all:Header/InvalidVersion”
            “title”: “Version 5 was supplied but Get Product Detail only supports x-min-v = 2, x-v = 3”
            “status”: 406,
            “meta”: {
                “xStatus”: “400”,
                “xCode”: “ERR_406”,
                “xTitle”: “Version 5 is Not Acceptable”,
           }

        }
    }
}

We would appreciate it if DSB could confirm that this interpretation is accurate. If the interpretation is accurate, then this transition approach and payload structure may cause issues, because existing clients would assume that two distinct errors have occurred and behave on that basis.

A better approach would be to ensure that changes to the error payload structure are non-breaking from the point of view of existing clients. Hence, instead of Option A2, we recommend that:

• An additional errorUrn field is added, perhaps in the “meta” object which contains the standardised error URN. Standardised client behaviour primarily relies on this field.
• Custom error codes continue to be provided through the “code” field. The “xCode” field is not included.
• Human readable descriptions for the purposes of trouble shooting continue to be provided through “title” and “detail”. The redundant xTitle field is not included.
• The “status” field always matches the HTTP response code as per jsonapi.org recommendations.
• The redundant xStatus field is not included – having two HTTP codes where only one aligns with the response is confusing.

Example error response under this representation:

{
    “errors”:
    [
        {
            “code”: “old error code”
            “title”: “error message”
            “status”: 406,
            “meta”: {
                “urn”: “urn:au-cds:error:cdr-all:Header/InvalidVersion”
           }
        }
    }
}

The advantage of an approach similar to this is that transition arrangements are simplified and less likely to cause issues for existing clients – the additional fields are added to server functionality and clients are updated at a later date. The representation is also more elegant in cases where no standardised URN has been defined. It is also unnecessary to set a depreciation date using this approach.

We agree with the suggested approach for response versioning – a carefully chosen URN scheme, non-breaking changes to error responses and the ability add new errors over time should avoid transition issues over time and the costs associated with version negotiation. We strongly oppose Option C1 and Option C3 – in any given implementation it is likely that many solution components which may generate errors are not suited to implementation of different behaviour based on a negotiated version.

Noting that there is significant change for data holders scheduled for 2021 we recommend a February 2022 implementation date. Modifying existing solutions to provide standardised error codes because a high proportion of solution components are likely to be affected. Data holders are already working to implement significantly increased scope during the November timeframe, including Phase 2 products for non-major brands, business and corporates and white-labelled products.

[ghost]

On behalf of AGL Energy CDR working group.

We are supporting of Option A2 that allows participants to define any custom error handling in ResponseErrorList_errors.

We are not supportive of Option C2:No endpoint versioning, as we consider error responses similar to success responses in that ADRs shouldn’t be surprised by contracts changing (except non-breaking changes). We are supportive of option C1:Version all end points as it contributes to more resiliency in the CDR system, even though it might mean more work for ADHs. We can see that DSB is doing efforts to make sure error responses is extensible and future proofing so we hope to see less breaking changes in error payload format in future.

We don't have a specific recommendation for "Transition arrangement" or "Obligation dates" as that's not applicable for energy at the moment.

[NationalAustraliaBank]

NAB welcomes the opportunity to provide the following feedback in relation to DP 154:

Payload Structure - NAB supports the proposed URN structure for the 'code' field of the error object

Specific error codes that extend the standardised error codes - NAB supports 'Option A2:Custom error codes as additional fields in ResponseErrorList_errors'

Transition Approach-

• NAB supports 'Option B3: Cutover to new error codes on a fixed obligation date' with transition tranches i.e.  phased approach to transition sets of end points. 
• NAB does not believe there is much value in supporting both old and new error codes (considering the overhead involved in delivering it). 
• Furthermore, we believe option B3 would be simpler for new ADRs entering into the ecosystem (as they won't have to worry about two sets of error codes).We believe that switching to new error codes would be simple and easy however, our preference is to do that in a phased manner i.e. transition a set of end points in stages then another set of end points and so on.

Response Versioning - NAB supports 'Option C2: No end point versioning'

[anzbankau]

We broadly agree with the approach of avoiding impacts to data recipients in this transition however we are unclear that the recommended option (Option B1: Return both old and new error codes during transition organic transition) will achieve this.

If for example a Data holder has to change their implementation to return a different HTTP response code - this will have to be a hard transition at a agreed point in time. Additionally, as per the analysis posted by Westpac, the error payload response changes will still have a impact to consumers in order to interpret correctly during the transition period.

Based on these two considerations we propose it will be more straightforward (on both data recipients and data holders) to choose 'Option B3 : Cutover to new error codes on a fixed obligation date'.

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 it would be appropriate to be scheduled for February 2022.

[PratibhaOrigin]

Feedback from Origin Energy on DP-154

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.

• Page 5 Optional error fields. These fields should be made include in particular xTitle & xStatus. xTitle would help in providing a meaningful details back to end user about the issue. Alternatively consuming application will have to develop a custom mapping for each of the errors.
• Decision on custom error codes - Origin’s preference is Option A2 as it suggests a clear and defined approach but also leaves the door open for future enhancements.
• Response Versioning (page 8)- Option C3, looks like a good compromise between no versioning of error response and using same version across both end point and error object structure. Question about version negotiation: is version negotiation happens before invocation of each API endpoint or once per session?
• Section B. Transition - This section doesn’t seem relevant to energy sector.
• Generic query - Do we need timestamp (when error happened) to be included into error object response?

As mentioned in the DSB call, Origin will work with DSB in future consultations and provide input on energy specific error codes and scenarios.

[ryderwj]

Decision A

Of the two options presented, Option A2 is supported

It is noted that status has been introduced into the errors structure. Is this intending to align closer with the jsonapi errors structure, similar to the discussion around the source attribute in the original 119 proposal? If so will this be considered mandatory or optional? When would the status represented in this error structure be different to the http level status code returned by the operation?

Decision B

I suspect in a number of implementations, additional custom coding will be required to return multiple errors in different representations for the same event if that is the intent of options B1 and B2.

Returning multiple error codes for the same event for a transitionary period will require changes to be performed twice, once to introduce the new representation and then again to remove the previous error representation.

Through this interim period, if there are any consumers of APIs that are using errors information in their processing, they must add additional logic to traverse the errors and determine whether the existence of multiple errors means the same thing, using a combination of the error and meta to de-duplicate.

Given the proposed obligation timing, it would appear that non-major ADIs will have a situation where a subset of API operations (from the July obligation) must support the combination of standard error codes and custom codes for the same event but API operations delivered from the November obligation will only support the standardised error codes.

In the interests of avoiding this transition complexity, options B1 and B2 are not supported. The preference is to be able move directly to the new error codes, with an obligation date set when this must be completed.

Decision C
The interplay of this decision item with Decision B is not entirely clear. Is the intent of versioning to control just the structure of errors or to also version the introduction of the new error catalog ?

Option C1, while ideal from a purist sense will result in every endpoint being versioned and the need to support multiple versions for an intervening period (in some cases partially across the API base, depending on the timing of the obligations against the non-major's delivery phasing as per previous comments). Given the consumer base is still relatively small is the cost of this approach warranted? Won't data recipients largely be forced to support the new model from November when non-majors deliver a set of functionality only to the latest version? This option is not supported.

Option C2 is supported for this initial introduction of error codes. The structural changes to errors are additive in nature and the initial introduction of a standardised error catalog into the standards for this situation is no different to a DH going live with their own set of error codes as is the case in the current standard.

Option C3 is not supported based on complexity compared to the likelihood of this capability actually being used.

[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. Because the feedback has resulted in a revised proposal for the presentation of errors to assist transition, this thread will be reopened for one week in case any participants want to provide feedback on the changes to be adopted. Feedback will close on Wednesday 21/04/2021.

Rather than respond to each specific comment from the community, the feedback has been summarised. A summary of feedback and changes arising from community responses has also been provided for Decision Proposal #155 and #156.

Feedback

Schema

• Option A2 was most broadly supported. This means that custom error codes will be defined within the meta object of standardised error response codes not URN extensions

Transition arrangements and versioning

• DHs did not support responding with custom and standardised error codes during transition, but did not articulate a solution that would assist ADRs to transition
• Versioning of error responses was not supported
• Preference is to avoid breaking changes to ADR clients during transition
• Divergent views on transition approach – DHs prefer direct cutover but this causes issues for ADRs
  Versioning of error responses was not supported

Obligations dates

• Community feedback from ADRs and DHs supported a mandatory phasing date commencing from February 2022 obligation date not November 2021
• ADRs supported a longer transition period to November 2022
• Banks noted existing high load of obligations to meet in November 2021 and they would prefer a later mandatory implementation date
• Non-major banks that support standardised error codes from July 1st wouldn’t require transition arrangements

Changes arising from feedback

The following changes are proposed to be made based on community feedback:

Obligations dates

• Change phasing obligations to commence February 2022; DHs can commence earlier and indeed this is favourable for non-major DHs who commence consumer data sharing obligations from July 1st 2021.
• Transition must be completed by November 2022 with all ADRs supporting standardised error codes

Transition arrangements

The options originally presented created breaking changes to ADRs during transition and feedback indicated that it created unwarranted overhead for DHs during transition. An alternative option has been identified by the community that removes any immediate breaking change to existing ADR clients and a simpler transition for DHs.

Specifically:

• Custom error codes are retained at the top-level during transition, rather than being provided in the meta response
• If a respondent is returning an application-specific error code, the URN must be provided in the meta object
• If a respondent is returning a standardised error code, the code is the URN value
• DHs MUST provide a mapping on their Dev Portal no later than the phase-in obligation date (February 2022). The format is unspecified and left to the discretion of the DH. This was supported in feedback provided to DP Decision Proposal 156 - Enhanced Error Handling: Custom Error Code Discovery Service #156
• Remove use of the status field as it is not required

The outcomes would be:

• Less breaking change for clients
• Lower change overhead for DHs
• Reliable, extensible and scalable
• Removes need for “status” field
• Supports programmatic discovery of changes
• Can be phased in by DHs in stages
• DHs can continue to support existing custom codes whilst qualifying the standardised error code that is is based on

Proposed structure

"ResponseErrorList_errorsV2" : {
  "required" : [ "code", "detail", "title" ],
  "x-conditional": ["meta"],
  "properties" : {
    "code" : { ...truncated for brevity... }, // If the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the meta object. Otherwise, the value is the error code URN."
    "title" : { ...truncated for brevity... },
    "detail" : { ...truncated for brevity... },
    "meta" : {	
      "$ref": "#/definitions/MetaError"
    }
  }
},
"MetaError": {
  "type" : "object",
  "x-conditional" : [ "urn" ],
  "description" : "Additional data for customised error codes",
  "properties" : { 
     "urn": {
        "type": "string",	
        "description": "The CDR error code URN which the application-specific error code extends. Mandatory if the error `code` is an application-specific error rather than a standardised error code."
     }
  }
}

Example standardised code

{ "errors": [ 
  { 
    "code": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount",    
    "title": "Invalid Banking Account",
    "description": "Description of the specific error encountered",
    "meta": {
      "urn": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount"
    } 
  } 
] }

Example custom code before transition

{ "errors": [ 
  { 
    "code": "old error code",
    "title": "error message",
    "description": "Description of the specific error encountered"
  } 
] } 

Example custom code during transition

{ "errors": [ 
  { 
    "code": "old error code",
    "title": "error message",
    "description": "Description of the specific error encountered",
    "meta": { 
      "urn": "urn:au-cds:error:cdr-all:Header/InvalidVersion" 
    } 
  } 
] } 

Example custom code after transition

{ "errors": [ 
  { 
    "code": "acme-bank:JointAccountElectionRemoved",
    "title": "Joint Account Consent Election Is Removed",
    "description": "Description of the specific error encountered",
    "meta": { 
      "urn": "urn:au-cds:error:cds-all:Resource/Unavailable" 
    } 
  } 
] } 

[spikejump]

If we may try to summarise our understanding here...

Non-major DHs joining the ecosystem SHOULD support the below on July 1st 2021. i.e. use of standardised error code and new payload structure.

{ "errors": [
  {
    "code": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount",
    "title": "Invalid Banking Account",
    "description": "Description of the specific error encountered",
    "meta": {
      "urn": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount"
    }
  }
] }

A made-up example of custom error code used by DHs in the ecosystems today.

{ "errors": [
  {
    "code": "DH-12345",
    "title": "Invalid Banking Account",
    "description": "Description of the specific error encountered",
  }
] }

DHs with custom error code post Feb 1st 2022. That is, as long as meta/urn block is introduced then DHs are compliant.

{ "errors": [
  {
    "code": "DH-12345",
    "title": "Invalid Banking Account",
    "description": "Description of the specific error encountered",
    "meta": {
      "urn": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount"
    }
  }
] }

If the above is correct then there does not seem to be a need of a "transition" period. ADRs need to look for standard compliant error in the meta/urn block. If found then that's the standard conforming error. If meta/urn is not found and it is before Feb 1st 2022 then code contains the custom (or standard conforming) error code. If meta/urn is not found and it is on or after Feb 1st 2022 then DH has a non-conforming implementation.

Transition seems to be only applicable when DHs intend to remove custom error code, in which case, it MUST happen by Feb 1 2022 to be compliant. (However, it seems as long as DHs introduce meta/urn block before Feb 1 2022 then whether DHs remove custom error codes is no longer relevant.)

Is the above correct?

Thanks.

[CDR-API-Stream]

Hi @spikejump for DHs coming into the ecosystem from July 1st 2021, that is correct. If they support the standardised error codes, they need only supply the URN error code in the code field.

The main purpose of the transition period commencing from Feb 1st 2022 is to allow DHs currently live with consumer data sharing to transition their API endpoints over an agreed period of time. This includes the initial four major DHs and reciprocal DHs like Regional Australia Bank who will require time and effort to transition. Noting there may be some non-major DHs that chose to go live on July 1st 2021 with custom error codes due to implementation schedules and release planning. Having a period of transition offers the most flexibility without adverse impacts to ADRs.

It also ensures that ADRs can discover what the DH will map their existing custom error codes to. If the DH chooses to retire their custom error codes completely, it would adversely impact ADRs if that was a hard cut over.

[NationalAustraliaBank]

NAB seeks confirmation of the below example after the transition period is as intended? From the decision proposal and the summary, we understand that the code at the top level will only have standard error code urn and any specific custom error codes must be supplied in the meta/urn attribute.

Example custom code after transition

{ "errors": [ 
  { 
    "code": "acme-bank:JointAccountElectionRemoved",
    "title": "Joint Account Consent Election Is Removed",
    "description": "Description of the specific error encountered",
    "meta": { 
      "urn": "urn:au-cds:error:cds-all:Resource/Unavailable" 
    } 
  } 
] } 

Also, please confirm our understanding on the proposed changes for NAB (and any other DH with custom error codes implementation as of July 1st 2021),

• From Feb 2022 (during transition) , meta/urn having the standard error code urn must be added to the current responses. The custom error codes in the top level code attribute will remain unchanged.
• From Nov 2022 (post transition), The code which is in meta/urn should be now supplied in the code at the top level and conditionally include meta/urn only if a custom error code is being included.

[CDR-API-Stream]

Hi @NationalAustraliaBank the example you provided is correct. Based one the feedback we received from the Decision Proposal, this alternative option was suggested by the community.

Your statements about the transitions are also correct. If the DH continues to support custom error codes they may continue to do so provided there is the meta/urn standard error code to ensure ADRs have a reliable way to interpret the error more generically.

[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.