Introduction
The following scenarios suggest specific error responses, or alternative error responses. The Consumer Data Standards sets down error codes specific to the Consumer Data Right. See:
General error issues not covered specifically in the CDS are discussed in CDS Guide, Error responses.
Where upstream normative standards such as OAuth, OIDC and FAPI apply, the error codes specified by those standards take precedence over CDS error codes.
The scenarios below are listed with the errors that may apply. Any specific conditions on how the errors apply are described in further detail.
Scenarios are listed under categories, but a scenario may overlap several categories.
Header errors
Missing required header: 400
If a call request is missing a header that is required by the Consumer Data Standards (CDS), then the Data Holder (DH) should respond with the appropriate 400 Missing Required Header, error code urn:au-cds:error:cds-all Header/Missing.
Examples of CDS-specific headers are the x-v or x-fapi-interaction-id.
The x-v request header represents the version of the payload response. It does not apply for error responses where a payload is not returned.
FAPI R/W requires x-fapi-interaction-id to be returned for successful and error responses. It is used as a correlation identifier between client request and server response.
The x-fapi-interation-id must be returned for any error to a requested protected resource as per the FAPI specifications. DSB recommends a response including the x-fapi-interaction-id where the client has provided an access token and is using Mutually Authenticated Transport Layer Security (MTLS).
Where the request's resource is not a voluntary protected resource or mandated protected resource, then returning x-fapi-interaction-id is at the discretion of the DH.
No x-min-v header provided: 406
If x-min-v header is not supplied it means that the client only supports a single version specified in x-v. A 406 Not Acceptable response is appropriate, if the versions requested are not supported.
Request for unsupported version of the x-v header: 406
If an unsupported header version is requested, such as a negative or non-integer value, then a 406 Not Acceptable error is a suitable response.
If an unsupported version is requested, such as a negative or non-integer value, then a 406 Not Acceptable error is a suitable response.
Authentication, Authorization and Consent arrangements
Authentication Error: 401
A refusal based on authentication returns error code 401 unauthorized.
Conditions for Invalid Consent Arrangement: 422
422 Invalid Consent Arrangement applies to all consent agreements and is to be returned under the following invalid arrangement ID scenarios:
- The arrangement being executed belongs to the customer specified by the supplied client id, but has previously been revoked
- The arrangement does not belong to the customer specified by the supplied client id
- The arrangement does not exist
CDR Arrangement ID mismatch behaviour
When a CDR Arrangement ID mismatch causes failed authentication, the appropriate response according to OAuth is to redirect with error code access_denied in the query component of the redirection URI, using the application/x-www-form-urlencoded format.
Authorisation server response to cancelling authentication
If a consumer decides to cancel during the authentication process, then the DH (authorisation server) should respond to the ADR (client) with an error outcome.
Confirmation dialog boxes in the authorisation flow
When critical errors are encountered during the Data Holder authorisation flow that cause the flow to break, is it acceptable to present a dialog box to the user stating that the authorisation cannot continue. For example, repeated use of an incorrect One Time Pin (OTP) would break the flow.
Arrangement revocation order of action: 204
ADR or DH arrangement revocation must occur synchronously with returning a 204 response to the caller.
Missing or non-matching sub claim responses: 400
When client authentication occurs against the token endpoint and the sub claim on the client assertion is missing or does not match the client, then the most appropriate response is to return 400: invalid_client in the body. This is indicated if an unknown client is encountered on the sub claim. Alternatively, it is also acceptable to return 400: unauthorized_client in the body as per RFC 6749 Section 5.2
Accounts
Accounts with no consent: 422
When accounts are involved in a request, consent must be supplied for all of the accounts and properties specified in the request. If one or more of those accounts is not included in the consent structure, then the request is invalid and a 422 Unprocessable Entity error response must be returned with no data.
Accounts that cannot be shared: 404, 422
In a call to the Get Accounts API, the DH should return only the list of accounts that can be shared. If an account is not shareable it must not be returned in the accounts list. For API calls that specify multiple accounts, where a request specifies an accountId that is not shareable, then an error must be returned.
If the accountId is requested in the URL (for example, Get Account Balance), the HTTP status code is 404 Not Found. If the accountId is provided in the request body (for example, Get Balances For Specific Accounts then a 422 Unprocessable Entity status code is returned.
Valid consent over multiple accounts: 422
When a DH has valid consents with several associated accounts, and if there is a reason not to disclose data relating to one of those accounts, then the DH should respond with a 422 Unprocessable Entity error response, specifying the list of accounts that will not be serviced. The ADR may then make a modified bulk API request, excluding the accounts that are not shareable.
API behaviour for closed accounts: 422
For an account that is closed but still eligible for data sharing, the DH should observe their obligations defined by the rules and make a determination as to whether they provide the direct debit data for a closed account in the current instance. An accountId may be requested but not shareable. An example is an account that has been closed for longer than two years, or 24 months. In this case, error 422 unprocessable entity should be returned, with the list of accountIds that cannot be shared. The ADR is then expected to request the data again with only the valid accountIds.
Providing accountId in Scheduled Payments response: 422
If the ADR does not have the consumer's consent to access the account data (for example, bank:accounts.basic:read privilege) then the DH returns an error, if the Get Accounts API is called.
Consent and account relationship: 422
If an accountId is specified in the URI or as a filter in a request but it is not associated to the consent, then the correct response should be 422 Unprocessable Entity.
Error code for account flagged as fraud or vulnerable: 403, 404, 422
For sensitive scenarios like fraud or consumer vulnerability, the disclosure of too much information could lead to harm. It is up to the DH to determine what data they provide in the error description. It is also up to the DH to determine the appropriate error code in these situations. Either error 403 or error 422 would be acceptable, as well as error 404, if the resource being requested is in the URL path. Unavailable Banking Account and Invalid Banking Account provide broad and generic error handling if a DH seeks to respond with error 404 or error 422.
Revoking one-off consent
When a consent has sharing_duration=0, the cdr_arrangement_id and consent are immediately expired upon creation. In this scenario, if the ADR calls the DH revocation endpoint with this cdr_arrangement_id, then the DH is expected to return an error if the revocation endpoint is called for an arrangement that has expired.
Eligibility for CDR for accounts that are written off: 404, 422
If the loan is written off or in arrears, but the account is still available, it is eligible for data sharing. However, if the DH blocks or suspends this account at their discretion then a 404 or 422 is an appropriate error response.
Consent revoked error response for invalid refresh and access tokens: 401
If an API is invoked by an ADR, but the consent has been withdrawn or cancelled, refresh token revoked and no access token is issued by the DH. This constitutes to an authorisation error with a corresponding oAuth error response. In this scenario, a 401 Unauthorised Error with a corresponding oAuth error response should be returned by the DH.
Transactions
GetTransactionDetails API response for Single Credit Transfer payments: 404
As a DH that only supports the base Single Credit Transfer (SCT) payments, rather than the additional overlay X2P1 payments, if an ADR attempts to call the Get Transaction Detail API, then the correct error to be returned is a 404 with error code urn:au-cds:error:cds-all:Resource/Invalid.
Handling transaction detail extended data when NPP is not supported: 404
If the DH does not have the requested extendedData, then the correct response is 404 not found. The isDetailAvailable field should be set to false for Get Transaction Detail calls if the DH does not support the NPP data.
Until other NPP services are included in the transaction payload or the payload is amended, a transaction can only validly have extendedData, if it was executed using the X2P01.01 overlay service. Other transactions should return false in the isDetailAvailable field and should return a 404 not found error response if extended data is requested.
HTTP status for a request for unavailable transactionId: 404, 422
The correct HTTP status response is 422, as the transactionId is valid and has been previously shared but is no longer available. HTTP status 404 indicates the transactionId was never valid and is unknown.
Extended data request: 404
Unless other services are included in the transaction payload or the payload is amended, a transaction can only validly have extendedData if it was executed using the X2P01.01 overlay service. Other transactions should return false in the isDetailAvailable field and should return a 404 Response if extendedData is requested.
General and enhanced error handling
Enhanced error handling API differences: 404, 422
In some cases, error codes differ across APIs. For example, Get Transactions for Account has both 404 Unavailable Banking Account and 404 Invalid Banking Account. The error code used depends in part on the way the resource is requested.
For bulk APIs that use POST method, the 404 not found error is not an applicable status code, as the resource is not presented in the URL. Error code 422 is used for bulk APIs via POST, where the requested resource cannot be found or returned.
Incorrect transaction dates: 400
In a call to Get Transactions for Account, if either the oldest-time or newest-time values are outside the supported range or are set to an impossible date, or the times are in conflict with each other, then the DH can respond with 400 Bad Request, error code urn:au-cds:error:cds-all:Field/InvalidDateTime.
Invalid product category query parameter: 400, 422
A DH can respond with a 400 Bad Request error, if the value sent as a product-category query parameter is not a valid product category.
A 422 Unprocessable Entity response is permitted where the DH receives a correct product-category (ie a valid enumerated type), but the DH knowingly does not offer that category of product to the market.
A 200 OK status response is also permitted in this scenario.
Invalid or unavailable energy account in request: 404
Where an energy account is invalid or unavailable as it is either blocked or suspended, the response is left to the discretion of the DH, with the guiding principle of whether future calls to the same resource are likely to receive a response. For instance, if the account is temporarily unavailable, due to a transient hold on the account, then error 404 Unavailable Energy Account is the appropriate response. However, for the protection of vulnerable consumers, or if the account is no longer associated with a valid consent, then error 404 Invalid Energy Account is the appropriate response.
Request rejected for a business rule: 400, 422
If the DH rejects the request due to a business rule, the appropriate response is a 404 not found or 422 Unprocessable Entity error response, depending on the API to which the DH is responding.
ADR authorisation
Accredited Data Recipient does not send a Client Certificate: 401
If an Accredited Data Recipient (ADR) does not send a Client Certificate when making a API call, then in accordance with RFC8705, the DH can return a 401 Unauthorised error.
ADR client certificate expired or not issued by CDR certificate authority: 401
If an ADR sends a Client Certificate that is expired or not issued by the CDR CA, then in accordance with RFC8705, OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens, the DH can return a 401 Unauthorised error response.
Invalid ADR call to UserInfo endpoint: 401
The Personally Identifiable Information (PII) data shared via the UserInfo endpoint is CDR Data. This includes the individual name or business consumer's agent name details, as well as any other claims the DH might support via the UserInfo endpoint. The ADR should not be allowed to collect data whilst they are inactive, suspended or revoked. A call from an invalid ADR to the UserInfo endpoint should fail, and receive a 401 response.
Inactive ADR calls UserInfo endpoint: 401
If an ADR is inactive and makes a request to the UserInfo endpoint, then it should receive a 401 response. The ADR should not be allowed to collect data whilst they are inactive, suspended or revoked.
ADR request impersonation: 401
When a consent initiation attempt is received, for an Accredited Data Recipient (ADR) with a request_uri bound to a different ADR, this is an invalid client authentication against the request_uri. The suggested error response is 401 Unauthorised.
Server errors
Partial failure in bulk API calls: 500
When responding to scenarios where a single source is unavailable in a bulk response, for example in a call to Get Bulk Balances, if a single account does not return a balance then, the DH should return a 500 Internal Server Error. The DSB recommends against partial responses.
Request for an unsupported HTTP method: 5XX, 405
If the DH receives a request for an unsupported HTTP method, the HTTP specification suggests the response should be a 501 error in accordance with RFC 7231, 6.6.2. For 5xx Unexpected Error Encountered scenario, the x-fapi-interaction-id should be included if possible. If the DH server implementation does recognise the method but does not support it, then HTTP response code 405 is required.
Server execution failure: 5XX
When a DH server error occurs, the DH should return a 5XX error code. The ErrorMetric schema returned by the Get Metrics endpoint is intended for errors arising from server execution.
Data Holder migrating between Service Providers: 404
If a DH migrates from one service provider to another and changes the endpoint for a set of CDR endpoints, then for an API call received to the original domain, the DH could respond with a HTTP 404 response indicating the service can no longer be found.
Metrics
Metrics for API calls that are rejected or return an error
Error API calls and rejected API calls should be included in metrics for all the reporting statistics for average response, Invocation metrics, Average TPS (Transactions Per Second), Peak TPS.
GetMetrics API Invocation count in certain error cases: 404, 405
If an authenticated high-tier API like GetAccounts responds with 404 not found or with 405 Method Not Allowed, then as far as invocations are concerned:
- A 405 error implies an invalid method is attempted against a resource. As the combination of method and resource do not exist, there is no invocation from the CDS perspective.
- A 404 error, resulting from an invalid (permanently unavailable or unknown) resource, is not an invocation. As the resource does not exist, there is no invocation from the CDS perspective.
- A 404 error, due to a temporarily unavailable account, is considered an invocation.
Non-disclosure due to a bad request is not refusal
As a response to an API call where data is requested from multiple accounts, it is acceptable for a DH to omit accounts that are not associated with consent. This non-disclosure due to lack of consent is not a refusal or rejection of service.
Timeouts in average response times for Get Metrics
Timeouts can be excluded from the AverageResponse times in Get Metrics calculations. However, they should still be counted as errors.
Availability metrics and latency
Latency that affects the quality of data may not be considered unavailability, but it would still be in breach of the data latency requirements in the NFR and should not be considered a successful outcome.
NFR thresholds exceeded: Too Many Requests: 403, 429
Under Exemptions To Protect Service a DH can respond with 429 Too Many Requests or 403 Forbidden error responses to protect themselves against too many or poorly designed or malicious multiple requests.
A refusal based on NFR thresholds being exceeded returns error 429 Too many requests.
Other error issues
Incorrect Page Parameter
For incorrect pageparameter no specific behaviour is defined, and the interpretation is left to the DH. The following are considered valid responses:
- A 200 OK response with no records and metadata populated as per normal.
- A 400 Bad Request response, recognising that an invalid page setting could be considered a malformed request.
- A 422 Unprocessable Entity response based on the interpretation of an invalid page number being valid according to the schema, but invalid based on business logic. In this case, an error payload must be supplied.
Additional or extra forward slash sent in request
If an ADR puts an additional forward slash '/', for example, Get/banking/accounts// instead of Get/banking/accounts/{accountId}, then the response to such requests with trailing slashes depends on the type of implementation the DH has in place, as it may vary depending on the API gateways, code libraries and specific code implementation for each API. For example, if the DH saw two trailing slashes and their implementation parsed this as a null resource identifier then it would be reasonable to return an error. Some DH implementations may see the two trailing slashes and ignore them and return the parent resource. Both behaviours mentioned above are valid.
Partial responses and multiple reasons for non-disclosure
The CDS require an error response and do not allow partial responses. When different issues result in different errors occurring, the error response is at the discretion of the DH. Different implementations may encounter those errors at different points in their implementation stack or application code. The error response depend on which error is encountered first.
AEMO API errors for multiple NMI requests
If there are errors resulting from the NMIs provided to AEMO, then depending on the error, the retailer must either correct the issue and re-submit the request to AEMO or relay the error back to the ADR.
Precedence of security conditions for determining error response
Precedence of error response determination based on security conditions is implementation specific. It is advisable to address coarse-grained errors first. For example, validate the ADR status before the Software Product status, or ensure the Access Token (AT) is valid before validating consent.
Authorising redirect on error for an inactive software product
When the client browser interacts with the authorise endpoint and encounters an invalid software product then the most appropriate response is to redirect back to the Software Product, which is the ADR application, providing error information.
Data Holder using custom error URN
It is permissible for a DH to use their own URN but it must be presented as a custom error code, not presented in the URN field. See CDS Error codes. DHs implementing custom error codes must choose one of the fallback CDR codes for use in the urn field so that ADRs can reliably map custom error codes for each DH to a generalised CDR error.
Null meta field in Get Balances For Specific Accounts request
When a DH receives a Get Balances For Specific Accounts request with null meta field value in the request body, it is within its rights to reject such a request with an error, but this may create a poor customer experience. The DH may choose to be more tolerant and allow the request to succeed, as there is nothing in the meta tag that is specifically needed for this request in any case.
Synchronising transaction request responses with the time of the request
The CDR does not specify how ADRs will call these APIs. DHs cannot rely on ADRs calling to get transaction detail immediately after getting a list of transactions. Transactions have identifiers that must adhere to ID Permanence requirements allowing ADRs to deterministically call the transaction detail API across subsequent calls. It is reasonable to expect that ADRs may request transaction details multiple times during the lifetime of a consent arrangement. How DHs deal with caching is an implementation consideration.
Comments
0 comments
Please sign in to leave a comment.