Decision Proposal 120 - CDR Error Codes for Enhanced Error Handling

[CDR-API-Stream]

This issue pertains to the consultation on a CDR Error Codes catalogue to cater for Enhanced Error Handling.

Specifically, this decision proposal is seeking to address the list of CDR-defined Error Codes for defining common errors, their definitions and their mapping to existing error scenarios where consistency across participants is advantageous.

The consultation draft Decision Proposal has been attached below:
Decision Proposal 120 - Enhanced Error Handling - CDR Error Code Catalogue.pdf

Feedback is now closed for this proposal. Feedback received will be considered and an initial position will be drafted and published in due course.

[perlboy]

Suggest CDR Error codes should be defined as ranges of numbers similar to how HTTP codes are defined (with x00 being a required "catch all" for Client Handling of a specific class type). This would allow for specifically defined errors to be outlined while allowing holders to expand on these error codes in a predictable way for clients.

[CDR-API-Stream]

The draft decision proposal for this issue has been posted in the issue description.

A working group meeting series to cover this and the other aspects of Enhanced Error Handling has been set up to walk through the decision proposals. Details are posted in the main issue.

[spikejump]

A few comments on the Decision Proposal PDF above.

• Page 5: Resource Entitlements: The text "The resource is protected and cannot be found" may be should be worded as "cannot be accessed" as the issue is that it is not that the resource can't be found but it is an entitlement question. If the resource can't be found then it should belong to the "Not Found" row above.

• Page 13: rows 21 and 22. The error scenario should be very explicit and clear so there's no ambiguity between the two. Otherwise, one DH interpret a condition to be InvalidBankingAccount and another DH interprets a condition to be UnavailableBankingAccount.

  • As an example, Accounts authorised for a consent can be changed post consent at the DH end. This seemed to be described by the description in row 22 - "The requested bank account is no longer associated to the active consent". However, in row 21 an almost identical statement is there - "the account is not associated to the consumer’s active consent". This ambiguity implies both are possible. But is this a good thing?

• A general call-out is to be very precise in the way the error code and descriptions are specified to avoid ambiguity. Avoid possible overlapping classification of errors which leads to ambiguity.

[perlboy]

Ha, @cdradr you got your Teapot, I look forward to you implementing this feature.

[cdradr]

@perlboy for any API that ADR has to implement to work around poor design decisions this would be the response (as prescribed by this decision proposal).

[NationalAustraliaBank]

Due to this decision proposal’s feedback period is coinciding with go-live activities, NAB requests that the decision proposal remain open for feedback until July 24th.

[CDR-API-Stream]

Given the final enhanced error handling workshop has been delayed to assist CDR participants who have go-live obligations in July, consultation has been extended until the end of July.

[ryderwj]

Proposal Feedback:

Normative References – Option 1 – (Don’t change normative references) is preferred. In a number of cases it will be impractical to override normative references where functionality is implemented by vendor products.

Error Code enumerations catalogue – Option 3 (extend Catalogue to all CDR flows) is preferred to ensure consistency and remove ambiguity across DH implementations

Error Catalogue:

Items 11,12,13 – depending on the DH implementation, normative standards may take precedence for the errors generated in these scenarios
Item 14 – Is this level of granularity required over and above the error definition for item 13?
Item 29 – In some unexpected error scenarios it will not be possible to generate a CDR specific error structure as they may be encountered by vendor products or other infrastructure layers

[anzbankau]

Please find below our feedback on the decision proposal:

Options support:
• Normative references: Option 1 – Don’t change normative references
• Error code enumeration catalogue: Not supportive of custom error codes accompanying common HTTP response codes/scenarios as this requires customisation while conveying little additional information. This means we would only support the CDR error codes specified against HTTP 422 response codes.

Feedback:
• p.22 proposed behaviour seems to contradict other decisions on invalid account id (i.e. elsewhere this scenario has the option of returning a 200 with a list of accounts that failed)

[mannharleen]

Feedback from Origin Energy on DP-120

Section on DP	Comment
None - General comments	Our take on the options: Normative references: Option 1 “Don’t change normative references” Error Code Enumerations Catalogue: Option 3: “Extend error catalogue to all CDR data flows”
Error Catalogue	Minor clarification Table item Decision Proposal 003 - Extensibility Model #3 “AU.CDR.Unexpected.Field”: Unexpected field in the request body parameter should be a 422. w.r.t normative reference to https://tools.ietf.org/html/rfc4918#section-11.2 Table item Decision Proposal 005 - Authorisation Granularity #5 “AU.CDR.Invalid.Field” Same comment as above

[WestpacOpenBanking]

We support Option 1 in relation to the Normative references – that the standards do not seek to define CDR Error Codes where the normative standards apply. This minimizes need for customisation of vendor supplied, certified security software and minimizes the risk of incompatibility with these implementations.

We most closely support Option 2 in relation to the Error Code Enumerations Catalogue. We think it is important to enumerate common errors where they impact the customer or developer experiences. Forcing consistency, especially in edge cases, may incur significant reimplementation effort and additional solution complexity with little benefit to customers or data consumers. In addition, over enumeration of response codes in circumstances which are neither necessary or useful to a data recipient could feasibly be used by an adversary during the reconnaissance phase of a cyber-attack. For example, the error codes

• AU.CDR.Resource.NotImplemented,
• AU.CDR.Resource.NotFound, and
• AU.CDR.Resource.Invalid

would appear to reveal additional information to an adversary with limited benefit (beyond a more generic error or even just an HTTP status code) to a data recipient or customers.

As previously stated, we believe that a degree of flexibility is needed for the standards to remain unambiguous, implementable and maintainable. This is because different data holders have different architectures, implementations and underlying data sources. We support the use of RFC2119 and the use of SHOULD or MAY in most circumstances.

Notwithstanding the above, we have the following specific comments on the proposed Error Catalogue:

• An example may be useful in relation to item 4.
• Enumerating specific error codes for specific invalid query parameters may be more detail than is needed. For instance AU.CDR.Invalid.DateTime, AU.CDR.Register.InvalidBrand and AU.CDR.Register.InvalidIndustry probably don’t add much useful detail beyond a more generic error time. This would especially the case if source is utilised in error objects.
• AU.CDR.Entitlements.InvalidAdrStatus suggests that the status is invalid, rather than not “active”, we suggest that AU.CDR.Entitlements.AdrStatusNotActive may be more descriptive.
• We would recommend that AU.CDR.Resource.NotImplemented be limited to specific cases, for example where a data holder in a certain sector is not required to implement a resource in that sector. However, it would be undesirable to necessitate deployments prior to the releases of functionality, or whenever unsupported endpoints in distinct sectors are released (e.g. Banks shouldn’t be required to return this error for energy endpoints).
• The description of AU.CDR.Entitlements.Forbidden should perhaps note that this error may be given if a joint account election is revoked by a joint account holder. Expected behaviour where an election is remade should also perhaps be discussed.
• Correctly returning AU.CDR.Resource.NotFound and AU.CDR.Resource.NotImplemented might be difficult in practice and not very useful for recipients – it may be better to retain a single error message aligned with the HTTP 404 status code.
• It may be of benefit to split many error codes depending on whether the condition is expected to be permanent or not. For example AU.CDR.Resource.UnavailableBankingAccount could feasibly correspond to temporary (system outage) or permanent (removed from consent) unavailability
• Unfortunately, Westpac is unable to implement GET /status/coffee or return the AU.CDR.IAmATeapot error at this time.
• The error code/error where a client does not request any version should be made clear.

[commbankoss]

For decision 1 - Normative References, Commonwealth Bank supports Option 1 - Don't change normative references. We believe normative references should be aligned to where possible, and see no benefit in overriding them.

For Error Code Enumerations Catalogue, we recommend option 3 - extend error catalogue to all CDR flows. We note that error codes will depend on which layer picks up the problem, and what can be done about it. Further clarification is required around the following points:

1. Regarding consent-revoked type errors: it may not be possible to differentiate between cases where consent has been revoked, and where a consent never existed. As such, we recommend additional flexibility around these errors to accommodate for different implementations, e.g. instead of MUST, use SHOULD
2. Regarding scenario 12: is an ADH-initiated suspension of an ADR to return the same error as a registry-initiated suspension of the ADR?

We also recommend a 6 months transition period, with details how the previous model and the new target model will co-exist.

[NationalAustraliaBank]

NAB supports the following Options outlined in section “Options Identified”.
Normative References – Option 1 – Don’t change normative references.
Error Code enumerations catalogue – Option 3 - extend Catalogue to all CDR flows.

Error Catalogue Feedback
Items 11, 12 – The response code 401 listed in the error catalogue contradicts with the 403 response code listed in “Appendix – Mapping of Error Scenarios from community issues” relating to issue 118.
Items 11,12,13, 14 – Depending on the DH implementation, normative standards may take precedence for the errors generated in these scenarios
Item 15 – 403 seems to be misaligned with Github 122 which suggests returning 404 or 422 for the same scenario:
• When a client tries to request a resource URL with a resource Id that exists but business rules prevent sharing the data for some reason, the Resource Server should choose to respond with a 404 (Not Found)
• When a Client tries to request a resource within a request body which exists but business rules prevent sharing the data for some reason, the Resource Server must respond with a 422 (Unprocessable Entity)
Items 15, 19 – In what scenarios would it be appropriate to return AU.CDR.Entitlements.Forbidden as opposed to AU.CDR.Resource.Invalid? There doesn’t seem to be any other guidance in the document regarding the usage of this error code.
Items 21, 22 – AU.CDR.Resource.UnavailableBankingAccount seems to overlap with AU.CDR.Resource.InvalidBankingAccount. E.g. Both codes cater for when an account is no longer associated to an active consent.
Item 20 – It is unclear what this error code would be used for as there is no other guidance relating to this error code. An example would be good to help illustrate the scenario.

General feedback –
• Providing one or more example error payloads for each code in the catalogue would be helpful to any ambiguity in the error scenarios.
• NAB questions the value of providing references within the error description of the actual erroneous data. For example, item 3 – whilst we agree there is value in returning error code ‘Unexpected Field Not Allowed’, we feel that providing a reference of the actual unexpected field in the error description creates unnecessary complexity.

[CDR-API-Stream]

This consultation is now being closed. Feedback received will be considered and an initial position will be drafted and published in due course.