Decision Proposal 121 - Application of existing HTTP Error Response Codes to Enhanced Error Handling

[CDR-API-Stream]

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

Specifically, this decision proposal is seeking to address the application of existing HTTP Error Response Codes to existing error scenarios and endpoints for clarification and uniformity in known use cases.

Note that this will only seek to address aspects of the standards where error handling is not already covered by normative references (such as OIDC).

The consultation draft Decision Proposal has been attached below:
Decision Proposal 121 - Enhanced Error Handling - Application of HTTP Response Codes.pdf

Feedback is now opened for this proposal. Feedback is planned to close on the 10th July 2020.

---

As part of the Enhanced Error Handling consultation a Working Group workshop series has now been set up. To register for the second workshop covering #121 and #122, please register your interest here: https://dsb_enhancederrors_workshop02.eventbrite.com.au

[perlboy]

406 does not currently specify that a payload is required or even supported.

Additionally version failure responses are marked as a should response code meaning that technically any http code is ok for an unsupported version.

[anzbankau]

ANZ would like to highlight some important handling around the account end points that have variable behaviour depending on:
• Account ID specified being invalid.
• Account ID specified being valid, but not part of the authorisation.
• Account ID specified being valid, and being part of the authorisation, but the customer is not currently entitled to share that account.

For these scenarios, if the standards are to be enhanced to specify how they are handled, we view the below as being appropriate.

All the below cases are in the context of a valid authorisation record being referenced.

Error Scenarios	HTTP Status
Single Account Endpoints
Invalid Account ID from ADR	400
Account not present in customer’s authorisation	400
Account in customer’s authorisation, but not currently entitled to share	403
Multi Account Endpoints
Some requested Account IDs from ADR are invalid. (Return the valid accounts)	200
All requested Account IDs from ADR are invalid. (Return empty array)	200
Some requested accounts not present in customer’s authorisation (Return the valid accounts)	200
All requested accounts not present in customer’s authorisation (Return empty array)	200
Some requested accounts that are in customer’s authorisation are not currently entitled (Return the valid accounts)	200
All requested accounts that are in customer’s authorisation are not currently entitled (Return empty array)	200

[anzbankau]

Based on the latest revision to the standards (v1.3.1) the above scenarios we mentioned appear to have been clarified.

There is now a statement against each of the multi-account-id end points that a HTTP 422 response is expected when:
The request was well formed but was unable to be processed due to business logic specific to the request. For this API a 422 response must be given if any of the account IDs provided are invalid for the consent context

Could it please be clarified that 'invalid' refers to all these scenarios:
• Account ID specified being invalid.
• Account ID specified being valid, but not part of the authorisation.
• Account ID specified being valid, and being part of the authorisation, but the customer is not currently entitled to share that account.

Which would mean the expectation from the standards for the multi-account-id end points is:

Error Scenarios	HTTP Status
Multi Account Endpoints
Some requested Account IDs from ADR are invalid.	422
All requested Account IDs from ADR are invalid.	422
Some requested accounts not present in customer’s authorisation	422
All requested accounts not present in customer’s authorisation	422
Some requested accounts that are in customer’s authorisation are not currently entitled	422
All requested accounts that are in customer’s authorisation are not currently entitled	422

[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 will be set up to walk through the decision proposals. Details will be posted in this issue thread when they are available.

[CDR-API-Stream]

As part of the Enhanced Error Handling consultation a Working Group workshop series has now been set up. To register for the second workshop covering #121 and #122, please register your interest here:
https://dsb_enhancederrors_workshop02.eventbrite.com.au

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

[mannharleen]

Feedback from Origin Energy on DP-121

We are very impressed by the quality and level of detail in this paper; it is educative and a great reference for future implementation phase.

We have the following comments/queries:

• For publicly available endpoints such as “get products”, there is no provision for authorization return headers such as 401 or 403. Does this imply that anyone is allowed to hit these endpoints, even non-ADR entities / non-registered entities?

• The paper acknowledges that in some circumstances the DH application may not be in control of the HTTP response code e.g. API GW may short circuit the request and add a response code that is not customizable. However, it is not clear what are the implications and steps required to mitigate such variations?

• On page 6, item Noting Paper 025 - Upcoming information security working group decision proposals  #25 “Data Request Not Found”, our understanding is that it should be a 422, because the resource identifier is in the body.

[ghost]

AGL Energy Feedback

We support the efforts to provide the above specifications with the following comments:

• We think it's unusual for a DELETE operation to use 204 No Content as oppose to a general convention of 200 OK.
• Regarding 304 Not Modified, we think this needs to be part of a larger caching specifications discussion.
• We suggest that the following noting be removed as it may risk consistency of application of these requirements:
  “It is noted that making this a MUST may not always be feasible where an API Gateway could be generically handling these issues.“

[commbankoss]

Commonwealth Bank recommends the following changes to the proposal:

• Current recommendation

  • HTTP Response Codes

    • We would like to emphasize that if the request is successful, but no information matches the criteria, 200 should still be returned
    • 406 Not Acceptable should only be related to content type (Accept headers); unsupported version should be 400

  • High level error scenarios

    • 13 (Requested Response Format Is Not Supported), 14 (Requested Response Charset is Not Supported), and 15 (Unsupported Media Type) all appear to be 415 Unsupported media type.
    • 17 (Unsupported Version) as above, 400 would be more suitable
    • 25 Not Found (resource identifier requested in the request body) should return a 422 as the URL itself may be fine, and the body is the problem.

  • HTTP Response Code Mapping to End Points

    • -
• Options Identifier
  • Normative References
    • -
  • When to use 404 vs 501 vs 405
    • 4 (Resource in Request Body does not exist or cannot be found) is fine, as long as we're consistent with 404s for bad URLs, and 422 for problems with the body.
    • 6 (Resource in Request Body exists but business rules prevent sharing) same as above.
  • When to use 422 vs 404 vs 400 vs 200
    • -
  • When to use 403 vs 404 or 422
    • 1 (Protected resource is in the URL but the resource Id is not associated with the consumer's consent) and 2 (Protected resource in the Request Body but the resource Id is not associated with the consumer's consent), as above, the solution for 404 and 422 scenarios must be consistent.
    • 2 (Protected resource in the Request Body but the resource Id is not associated with the consumer's consent) the error scenario is not consistent with the description; Access Token is valid in the scenario, but invalid in the description.
  • When to use 406 vs 400
    • As above, 406 should only apply for Accept headers. As such, 400 should apply for bad version.
  • Consent Revocation
    • We require further analysis on this section.
  • Customer Records, Accounts and Consent
    • We do not see the need to return additional information for these:
      • Don't think we can identify the situation before we deny the request, particularly if account request is in the URL
      • It's difficult for ADRs to code against a description as the description is likely to be different for each data holder
      • There needs to be a way to tell DR the account has been removed, but this isn't the way
    • 1 (The consumer removes election of the account) and 2 (A Joint Account holder has withdrawn consent election to an account) could be the same error
    • 3 (The consumer no longer owns the account) and 4 (The account Id is invalid / not associated with the consumer's consent (including the resource requested is just wrong)) could just return "account not found".

[CDR-API-Stream]

Hi @anzbankau

Could it please be clarified that 'invalid' refers to all these scenarios:

• Account ID specified being invalid.
• Account ID specified being valid, but not part of the authorisation.
• Account ID specified being valid, and being part of the authorisation, but the customer is not currently entitled to share that account.

This is correct. Where an ADR requests the data for an Account ID under those three scenarios it would result in an error. Noting that the currently recommendation in #122 is the application of 404 Not Found when the resource identifier is presented in the URL (path parameter).

[CDR-API-Stream]

Consultation on this decision proposal will be extended until 10th July to elicit further feedback. Feedback received in this and the related enhanced error handling DPs will be reviewed and updated DPs provided for review accordingly.

[CDR-API-Stream]

We have the following comments/queries:
For publicly available endpoints such as “get products”, there is no provision for authorization return headers such as 401 or 403. Does this imply that anyone is allowed to hit these endpoints, even non-ADR entities / non-registered entities?

Hi @mannharleen that is correct. Get Products, Get Product Details, Get Outages and Get Status APIs are public, unauthenticated, endpoints. In effect any public API client can call these APIs.

The paper acknowledges that in some circumstances the DH application may not be in control of the HTTP response code e.g. API GW may short circuit the request and add a response code that is not customizable. However, it is not clear what are the implications and steps required to mitigate such variations?

The DSB would welcome feedback from ADRs and DHs in this regard. The assumption is that some situations will be handled under SHOULD or MAY guidance to give DHs flexibility where there is likely to be less ability to control/customise the error response. This would still set expectations because SHOULDs remain strong recommendations but do not make the standards too rigid in situations this is not necessary.

The standards may also consider a SHOULD (e.g. should be a 406) for a specific error code and a MUST for the class of error codes (e.g. must be a 4xx). The standards may also consider where the HTTP status code can be a MUST however customising the error payload is a SHOULD.

Some of the considerations when an error code should be a MUST:

• It is reasonable to expect the to be encountered within the API application code or within control of the DH to handle the error scenario explicitly
• The consumer is present and remediation of the error involves consumer input/action or is important for the consumer to comprehend the issue encountered
• The error relates to the consent arrangement (e.g. when a data request for an account balance is made but the account is no longer associated to consent)
• When the error is encountered, it is likely that the ADR can gracefully handle and renegotiate the data request in realtime (in other words, it wouldn't require triage and analysis of the issue and a code change to the ADR software product to fix)

On page 6, item #25 “Data Request Not Found”, our understanding is that it should be a 422, because the resource identifier is in the body.

You are correct. If the resource identifier is provided in the request body, a 422 Unprocessable Entity should be returned, not a 404 Not Found

[CDR-API-Stream]

Hi @AElharouny

DELETE request

AGL Energy Feedback

We support the efforts to provide the above specifications with the following comments:

We think it's unusual for a DELETE operation to use 204 No Content as oppose to a general convention of 200 OK.

A 204 No Content is accepted practice when a successful response will not return a response. Per RFC7231:

4.3.5. DELETE
If a DELETE method is successfully applied, the origin server SHOULD
send a 202 (Accepted) status code if the action will likely succeed
but has not yet been enacted, a 204 (No Content) status code if the
action has been enacted and no further information is to be supplied,
or a 200 (OK) status code if the action has been enacted and the
response message includes a representation describing the status.

304 Not Modified

Regarding 304 Not Modified, we think this needs to be part of a larger caching specifications discussion.

The DSB would welcome any feedback or a change request raised on Standards Maintenance.

Noting statements

We suggest that the following noting be removed as it may risk consistency of application of these requirements:
“It is noted that making this a MUST may not always be feasible where an API Gateway could be generically handling these issues.“

Thanks @AElharouny, this has been noted.

[CDR-API-Stream]

Hi @commbankoss, thanks for the detailed feedback.

Current recommendation

• HTTP Response Codes
  • 406 Not Acceptable should only be related to content type (Accept headers); unsupported version should be 400

Can you elaborate why 406 would not be acceptable? The data standards currently expect 406 Not Acceptable.

406 Not Acceptable indicates that the client could not negotiate a valid representation of the requested resource and the server is unwilling to return a default representation. ADRs can negotiate the version of the resource representation using x-min-v and x-v. 406 seems valid in the event that a representation cannot be returned because the DH does not support any version in the range the ADR requested.

Per RFC7231:

The 406 (Not Acceptable) status code indicates that the target
resource does not have a current representation that would be
acceptable to the user agent, according to the proactive negotiation
header fields received in the request (Section 5.3), and the server
is unwilling to supply a default representation.

This is different to the ADR requesting a malformed or invalid version (i.e. not a positive integer) which would return a 400 Bad Request.

[CDR-API-Stream]

Hi @commbankoss,

High level error scenarios

13 (Requested Response Format Is Not Supported), 14 (Requested Response Charset is Not Supported), and 15 (Unsupported Media Type) all appear to be 415 Unsupported media type.
17 (Unsupported Version) as above, 400 would be more suitable
25 Not Found (resource identifier requested in the request body) should return a 422 as the URL itself may be fine, and the body is the problem.

Scenarios 13 and 14
Scenarios 13 and 14 relate to the Accept-* headers where the ADR request is for the DH response to be represented in a particular format. In this situation, the Content Negotiation section of RFC2731 would apply and a 406 Not Acceptable would be expected.

For the ACDS,

• if the media-type in the Accept header doesn't match application/json (or a wildcard, e.g. */*), return 406 Not Acceptable. The response should indicate "we only serve JSON here".
• If the character set (charset) in the Accept header (or Accept-Charset) doesn't match utf-8, return 406 Not Acceptable. The response should indicate "we only serve UTF-8 character encoding here".
• If the ADR doesn't provide an Accept header, the media type defaults to "application/json"

Scenario 15
Scenario 15 relates to the Content-Type and format of the data the ADR is providing the DH.

In effect, 406 Not Acceptable would be returned by the DH when the DH can't respond based on accepting the request headers (i.e. the ADR provide an Accept header which states they only want XML but the DH only supports the JSON representation).

415 Unsupported Media Type would be returned by the DH when the data sent in the request body (content in a POST or PUT) is an unsupported media type (i.e. the ADR sent XML but the DH can only accept JSON data).

[CDR-API-Stream]

Hi @commbankoss

HTTP Response Code Mapping to End Points
-
Should there have been any feedback provided here? Noting this is also used in other sections of your response.

[CDR-API-Stream]

Hi @commbankoss

When to use 404 vs 501 vs 405

• 4 (Resource in Request Body does not exist or cannot be found) is fine, as long as we're consistent with 404s for bad URLs, and 422 for problems with the body.
• 6 (Resource in Request Body exists but business rules prevent sharing) same as above.

Noted and agreed. The purpose of the HTTP status code in these situations only differentiates the way the resource was requested not the status of the resource.

[CDR-API-Stream]

Hi @commbankoss,

Customer Records, Accounts and Consent

• We do not see the need to return additional information for these:
  • Don't think we can identify the situation before we deny the request, particularly if account request is in the URL

Can you please elaborate?

• It's difficult for ADRs to code against a description as the description is likely to be different for each data holder

When a resource cannot be returned, the current expectation is the description only includes the resource identifier to allow ADRs to code against it.

• There needs to be a way to tell DR the account has been removed, but this isn't the way

The DSB would welcome any further options in this respect.

[CDR-API-Stream]

406 does not currently specify that a payload is required or even supported.

Hi @perlboy thanks for noting these concerns. This will be considered in the final Decision Proposal.

Additionally version failure responses are marked as a should response code meaning that technically any http code is ok for an unsupported version.

We'd welcome input from the community regarding the treatment of must vs should in these situations. The expectation is that a SHOULD aligns to RFC2119 meaning it is a strong recommendation and a DH needs a valid, justifiable reason for not implementing it.

3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.

[perlboy]

We'd welcome input from the community regarding the treatment of must vs should in these situations. The expectation is that a SHOULD aligns to RFC2119 meaning it is a strong recommendation and a DH needs a valid, justifiable reason for not implementing it.

I don't really see any reason why these shouldn't (no pun intended) be MUST.

Arguing with a DH over a "valid, justifiable reason" is like pulling teeth in my early experience of doing so (over x-v treatment).

[CDR-API-Stream]

Thanks @perlboy input like this will be useful in shaping guidance for which error codes are musts for all data holders.

[anzbankau]

Please find below our feedback on the decision proposal:

• p.6, Scenario 24 - Should say 'if any account' to cater for scenarios where there is a mix of invalid and valid accounts.
• p.32, Auditing - Text states: Auditing In all of these situations it is expected that a Data Holder would record the reasons and the rejection must be included in the Data Holder's metrics obligations.
  • This would require a level of complexity in the reporting and metrics solution that was not anticipated. As such, ANZ would like to review the necessity of this degree of logging from a deliverability and maintainability perspective.
• p.33, Situation 4 - The proposal is that we give a meaningful error in cases where we reject sharing due to invalid account id/not associated. This feels like it may provide too much information in some cases.

[jimmcslim]

Reviewing the proposal I wonder if it should incorporate RFC7807 - https://tools.ietf.org/html/rfc7807 - which:

defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

...as a way for additional error information to be communicated in a standard way (where appropriate from a security and privacy perspective), beyond the HTTP response status code.

[ryderwj]

After review of the proposal, have comments related to one item:

Item 7 Page 20 (no business data)

• If a request is made for a resource that doesn’t exist then the result should be a 404
• In the transaction detail example there are some mandatory attributes that need to be set to return an empty object
• Looking beyond the TransactionDetail example, if an OK response is required, is a 204 more appropriate when there is no data?

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