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:
codefield MUST be present: holds an endpoint specific error code. This MAY be a standard CDR error code or an application-specific error code.titlefield MUST be present: holds a human readable label of the error that is constant per code.detailfield MUST be present: holds a human readable description of the specific error.metaobject 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 Title | Error Code | HTTP Status Category | Description |
|---|---|---|---|
| Expected Error Encountered | urn:au-cds:error:cds-all:GeneralError/Expected | 4XX | An error code that can be used, when an expected error occurs that is otherwise not covered by a more specific error. |
| Unexpected Error Encountered | urn:au-cds:error:cds-all:GeneralError/Unexpected | 5XX | An error code that can be used, when an unexpected error occurs. |
| Service Unavailable | urn:au-cds:error:cds-all:Service/Unavailable | 503 (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 Title | Error Code | Description |
|---|---|---|
| Invalid Field | urn: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. |
| Invalid Header | urn: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. |
| Invalid Date | urn:au-cds:error:cds-all:Field/InvalidDateTime | An invalid date is provided. |
| Invalid Page Size | urn:au-cds:error:cds-all:Field/InvalidPageSize | The value provided in the page-size pagination field is greater than the maximum allowed by the Consumer Data Standard (page_size >1000). |
| Missing Required Field | urn: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. |
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 Title | Error Code | Description |
|---|---|---|
| Invalid Resource | urn: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. |
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 Title | Error Code | Description |
|---|---|---|
| Invalid Page | urn: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. |
451 (Unavailable for Legal Reasons) Errorsβ
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 Title | Error Code | Description |
|---|---|---|
| Legal Block | urn: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. |
| Ineligible Block | urn:dio:error:cds-all:Resource/IneligibleBlock | This status code indicates that the Customer is ineligible for CDR Data Sharing. |
| Call Center Block | urn:dio:error:cds-all:Resource/CallCenterBlock | This status code indicates that the consumer should call the Call Center for further information. |
500 (Internal Server Error)β
| Error Title | Error Code | Description |
|---|---|---|
| Internal Server Error | urn:au-cds:error:cds-all:GeneralError/Unexpected | This status code indicates that the server encountered an unexpected condition and can't fulfil the request. |