Standardize Error Handling AIS

[simonmeyerm]

The AIS specification is interpreted differently by the service providers, which leads to inconsistency in returning errors. Consumers of the API need to implement specific rules for each service provider individually. This is contradictory to the standardized approach of the common API. According to the feedback of the Service Providers, SIX created a first draft with a recommendation of how to handle different business cases of the AIS API Endpoints:

/account/{accountId}/balances

• Must always be returned
• Non-Business Days: Return balance of last available day

/account/{accountId}/transactions

• Non-Business Days: 404 - RESOURCE_DOES_NOT_EXIST
• No Bookings for requested day: 404 - RESOURCE_DOES_NOT_EXIST (To be clarified)

General JSON Endpoint responses: Intraday - Supported

• Returns the intraday data (booked balance (ITBD) or transactions), if called without a date.
• Returns the closing data (booked balance (CLBD) or transactions), if called for a past date.
  • In case the specified day has not yet been finalized, the response will be a 404 - RESOURCE_NOT_READY.

Intraday - Not Supported

• 404 - NOT_IMPLEMENTED

/iso20022/statements/{reportId}

• Ressource not yet generated: 404 - RESOURCE_NOT_READY

The goal should be that the community agrees on a standard that would be documented within the API specification itself or on the SFTI Website.

To be more specific about Intraday- Data: Intraday Data are only completed as of Day-End-Processing of the next day. To avoid confusion with the specific date, intraday data must be requested with date parameter = empty.

To be clarified: Unified Error Handling requires CommonErrorReponse - Type as mandatory in order to ensure that the issue can be identified. -> Change Type in CommonErrorResponse to required for AIS and Payment API

[juergen-petry]

Have a possibly somewhat stupid question: Shouldn't HTTP error codes (here: 404) be reserved for technical errors? Otherwise you can't distinguish between an endpoint that doesn't exist and a call that returns an empty list - or is this to be achieved by supplementing the error code with a human readable message describing the problem?

[simonmeyerm]

Have a possibly somewhat stupid question: Shouldn't HTTP error codes (here: 404) be reserved for technical errors? Otherwise you can't distinguish between an endpoint that doesn't exist and a call that returns an empty list - or is this to be achieved by supplementing the error code with a human readable message describing the problem?

The HTTP status codes are used for the general communication of requests between client and server. Where in our APIs, 2XX codes are used for successful, 4XX for client errors and 5XX for Server error responses. The errors responses must comply to the defined commonErrorResponse of the specification and gives the possibility to specify the error further (with the error type enum) or a kind of human readable message (with error title, detail and instance) for troubleshooting.

In the SFTI specifications the errors are defined as e.g. "404 - Not Found - Either the endpoint does not exist or a requested resource is not yet available (e.g., account statements)" The commonErrorReponse is then used to give more specific information about the error.

[simonmeyerm]

Input / Rewrite from ZKB:

GET /accounts/{accountId}/balance Retrieve account balance information (requestAccountBalance)

• If called without a date: Returns the current intraday booked balance (ITBD, as in camt.052) at the time of the call on success (200).

  • Implementation is optional.
  • Valid 404 errors:
    • 404 - NOT_IMPLEMENTED: Provider does not support intraday balance

• If called with a date: Returns the closing booked balance (CLBD, as in camt.053) for that date on success (200).

  • Implementation is mandatory.
  • Valid 404 errors:
    • 404 - RESOURCE_DOES_NOT_EXIST: date without an account closing ever (there will never be a closing booked balance for that date, retrying call makes no sense)
    • 404 - RESOURCE_NOT_READY: date with an account closing, but closing hasn't happened yet (retry again later)

GET /accounts/{accountId}/transactions Retrieve transactions of a specific account (requestAccountTransactions)

• If called without a date: Returns all transactions since last account closing (as in camt.052s for that day) on success (200). List of transactions may be empty.

  • Implementation is optional.
  • Valid 404 errors:
    • 404 - NOT_IMPLEMENTED: Provider does not support intraday balance

• If called with a date: Returns all transactions for that date (as in camt.053) on success (200). List of transactions may be empty.

  • Implementation is mandatory.
  • Valid 404 errors:
    • 404 - RESOURCE_DOES_NOT_EXIST: date without an account closing ever (there will never be transactions for that date, retrying call makes no sense)
    • 404 - RESOURCE_NOT_READY: date with an account closing, but closing hasn't happened yet (retry again later)

Notes:

• Banks should be free to choose account closing dates, even though most banks will have account closings on bank working days only today. Note there is no relevant worldwide bank working day/bank holiday calendar.
• We should probably use a self explaining error code like DATE_WITHOUT_ACCOUNT_CLOSING instead of RESOURCE_DOES_NOT_EXIST for that case.

[juergen-petry]

Input / on behalf of UBS:

Our opinion: We agree with the comment that error 404 should be reserved for technical errors and therefore and shouldn't be applied to the use cases described in the issue (business errors).

In other words: The conclusion was that for the use cases listed in the GitHub issue, status code 404 is not the best choice, not that HTTP status codes are inappropriate in general. We think using “problem+json” would be the most appropriate solution, e.g. as described here: https://github.com/swissfintechinnovations/ca-payment/blob/91c5b75f73b899781a47d58be7d036467db86eae/accountAPI.yaml#L1045

[dkoeni]

Issue resolved with v1.5.2