Skip to main content

Error Handling

Biza API definitions can return a variety of errors if something goes wrong. Every error has an HTTP Status Code, and will also return an Error type and brief explanation when the error is triggered.

When using an API it is important to keep in mind that whilst errors and exceptions (e.g., server connection problems or outages) are rare, do happen in general operation. To ensure your integration is reliable, you must actively monitor for errors and exceptions. To make diagnostics simpler it is important to log as much detail as possible including when the call was made, to what URL it was made to, the parameters provided, and ideally the x-fapi-interaction-id.

If you need to contact support, we recommend including the complete request, when it was sent, any response received and other identifiers included in the request.

Response​

We adopt an extended version of the Consumer Data Standards Error Codes.

The primary component of the response is the errors object, which will be an array of zero or more unnamed objects.

The fields in each of these objects is as follows:

  • code field MUST be present: holds an endpoint specific error code. This MAY be a standard CDR error code or an application-specific error code.
  • title field MUST be present: holds a human readable label of the error that is constant per code.
  • detail field MUST be present: holds a human readable description of the specific error.
  • meta object MAY be present: holds additional endpoint specific data relevant to the error.

If Data holder responds with an application-specific error code, the standard CDR URN error code must be provided in the MetaError object.

URN Structure​

When responding with a standard CDR error code, the URN structure is defined as follows:

urn-string = "urn:" NID ":" metatype ":" sub-type ":" error-category "/" error-code

NID = au-cds (Upstream Standards Error) / dio (Biza Specific Error)
metatype = 'error' string.
sub-type = cds-all / cds-register / cds-banking / cds-energy
cds-all = "cds-all" string. An error common to all API responses,
cds-register = "cds-register" string. Reserved for CDR Register issued error codes only,
cds-banking = "cds-banking" string. An error code specific to the CDR banking APIs only,
cds-energy = "cds-energy" string. An error code specific to the CDR energy APIs only.
error-category = string. The high level category code for the error defined in the Consumer Data standards
error-code = string. The specific error encountered, defined in the Consumer Data Standards.

Glossary​

General Errors​

Error TitleError CodeHTTP Status CategoryDescription
Expected Error Encounteredurn:au-cds:error:cds-all:GeneralError/Expected4XXAn error code that can be used, when an expected error occurs that is otherwise not covered by a more specific error.
Unexpected Error Encounteredurn:au-cds:error:cds-all:GeneralError/Unexpected5XXAn error code that can be used, when an unexpected error occurs.
Service Unavailableurn:au-cds:error:cds-all:Service/Unavailable503 (Service Unavailable)A request is made but the API unavailable as due to an outage.

400 (Bad Request) Errors​

The 400 Bad Request Status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

Error TitleError CodeDescription
Invalid Fieldurn:au-cds:error:cds-all:Field/Invalid

Applies when the value of the URL parameter or request body parameter is an invalid type or the value violates the field's constraints as defined by the interface contract.
The error detail SHOULD be the parameter name of the invalid field. The error detail MAY include further details explaining the valid format.

Invalid Headerurn:au-cds:error:cds-all:Header/Invalid

Applies when a HTTP Header is provided but the value provided is an invalid type or violates the field type constraints as defined in the Consumer Data Standards.
The error detail SHOULD be the HTTP header name. The error detail MAY include further details explaining the valid format.

Invalid Dateurn:au-cds:error:cds-all:Field/InvalidDateTime

An invalid date is provided.
For example, a future date value is expected, but a date in past or current date is supplied. Applies to DateTimeString, DateString, and TimeString field types.
The error detail SHOULD be the parameter name of the invalid date field.
The error detail MAY include further details explaining the expected date value.

Invalid Page Sizeurn:au-cds:error:cds-all:Field/InvalidPageSizeThe value provided in the page-size pagination field is greater than the maximum allowed by the Consumer Data Standard (page_size >1000).
Missing Required Fieldurn:au-cds:error:cds-all: Field/Missing

The request is missing a mandatory field required for the API. It may be a missing query parameter or missing field in the request payload.
The error detail SHOULD be the parameter name of the missing field.

404 (Not Found) Errors​

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent.

Error TitleError CodeDescription
Invalid Resourceurn:au-cds:error:cds-all:Resource/Invalid

The requested resource identifier is permanently unavailable. No subsequent request for the resource will be successful. Applies when the resource ID is provided in the URL.
The error detail is the resource ID of the resource being requested.

422 (Unprocessable Entity) Errors​

The 422 status code means the server understands the content type of the request entity, and the syntax of the request entity is correct but was unable to process the contained instructions.

Error TitleError CodeDescription
Invalid Pageurn:au-cds:error:cds-all: Field/InvalidPage

The page being requested is out of range. For example, the valid pagination range is 5 pages and the client requested page = 10.
The error detail SHOULD be the maximum number of pages that are available.

The 451 client error response code indicates that the user requested a resource that is not available due to legal reasons, such as a web page for which a legal action has been issued.

Error TitleError CodeDescription
Legal Blockurn:dio:error:cds-all:Resource/LegalBlock

This status code indicates that the server is denying access to the resource as a consequence of a legal demand.

The server in question might not be an origin server. This type of legal demand typically most directly affects the operations and search engines.
For example, criminal court cases, civil court cases, tribunals, statutes/laws, treaties, or simply a request from a company legal department are instances where 451 may be appropriate.
The error detail SHOULD include an explanation, in the response body, of the details of the legal demand: the party making it, the applicable legislation or regulation, and what classes of person and resource it applies to.

Ineligible Blockurn:dio:error:cds-all:Resource/IneligibleBlock

This status code indicates that the Customer is ineligible for CDR Data Sharing.
The error detail SHOULD include an explanation, in the response body, of the details of the ineligible block.

Call Center Blockurn:dio:error:cds-all:Resource/CallCenterBlock

This status code indicates that the consumer should call the Call Center for further information.
The error detail SHOULD include an explanation, in the response body, of the details of the call center block.

500 (Internal Server Error)​

Error TitleError CodeDescription
Internal Server Errorurn:au-cds:error:cds-all:GeneralError/UnexpectedThis status code indicates that the server encountered an unexpected condition and can't fulfil the request.