Skip to content
Developerhome
Product homepage
Banking Service

Errors

  Less than to read

Like any other RESTful API there are times when an error might occur when making a HTTP request. For example, a database might be unreachable, resulting in a ‘Internal Server Error (500)’. The Transaction Import Connector has various error responses, which are returned as a result of different unsuccessful HTTP request.

There is also an errorDetails object which exists on the transaction import request itself. You can see the errorDetails object when making a GET request on a transaction import request. The different values for the HTTP error responses and the errorDetails object will be discussed in more detail on this page.

HTTP error response codes

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "Object",
            "code": "InvalidPropertyDataType",
            "message": "BatchTask.iterations is not of a type(s) number"
        ],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "name",
            "code": "InvalidPropertyValue",
            "message": "BatchTask.name does not match pattern "^@sage/[a-z0-9.]{1,64}$""
        ],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "ImportRequest.data.apiType",
            "code": "RequiredPropertyMissing",
            "message": "ImportRequest.data requires property "apiType""
        ],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "ImportRequest.data.bankAccounts",
            "code": "DuplicatedField",
            "message": "The BankAccount with id 8f26aa5a-f51c-46ec-912f-a98aa37fec52 is a duplicate within the sent data"
        ],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "additionalProperties",
            "code": "AdditionalPropertyFound",
            "message": "error.stack"
        ],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "details": [
            "target": "File",
            "code": "InvalidSourceData",
            "message": "Invalid data"
        ],
        "status": 400
    }
}

A validation error is typically seen when 1 or more fields in the supplied data or file failed to meet the specification. An error code of ‘ValidationError’ along with some details of what failed to match the specification in the ‘details’ will be returned. note: the code within the details of each ValidationError can be surfaced at the top level in place of ValidationError

In each of the examples, there is a data validation error. The errors are:

  • A field is not the expected type for example the batchTask.name field does not match the pattern.
  • Duplicated fields, for example the bankAccountId is sent 2 times.
  • The field is missing, for example, the apiType not being included on the import request object.
{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ProcessingError",
        "message": "Failed to delete Batch from Provider API",
        "details": [],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ProcessingError",
        "message": "The TransactionImport is not in the correct state for this operation",
        "details": [],
        "status": 400
    }
}

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "ProcessingError",
        "message": "An error occurred while processing the request",
        "details": [],
        "status": 500
    }
}

A ‘ProcessingError’ code is widely used and can be returned with a variety of status codes, depending on where the error occurred. You’ll typically see this if a database operation to get, modify or delete a transaction import was unsuccessful. For example, if you try to confirm a transaction import before it’s in 1 of the required ‘accepting’ statuses, you’ll see the ‘ProcessingError’ code returned.

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "AbandonSilentlyError",
        "message": "The TransactionImport is not in the correct state for this operation",
        "details": [],
        "status": 400
    }
}

An ‘AbandonSilentlyError’ error code will occur in the step function of the transaction import connector. If the transaction import is not in the correct state for the operation. For example, if a transaction import has already been deleted when the step function attempts to delete it.

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "AuthorizationError",
        "message": "The provided credentials are not valid for this request",
        "details": [],
        "status": 401
    }
}

‘AuthorizationError’ is a widely used error code if an authorisation check fails. For example, if the company making the GET request, is making a request for a different organisation.

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "InternalServerError",
        "message": "An error occurred while processing the request",
        "details": [],
        "status": 500
    }
}

An ‘InternalServerError’ is normally returned in circumstances where a more useful error cannot be returned. Often meaning something unexpected occurred in the processing of the import.

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "NotFoundError",
        "message": "No TransactionImport found",
        "details": [],
        "status": 404
    }
}

This is returned when a transaction import cannot be found by a GET request.

{
    "data": null,
    "links": null,
    "meta": null,
    "error": {
        "code": "TooManyRequests",
        "message": "Too many requests made, throttling for this organisation",
        "details": [],
        "status": 429
    }
}

This is returned by the API throttler. It’ll be returned when there are too many requests made in a given time period by a single organisation.

The errorDetails object

Throughout a transaction import’s lifecycle it can encounter various pieces of information, warnings or errors. All of which could be useful to the end user. As a result, we capture and record this information on the transaction import itself and this is visible on a GET request.

An error will always try to be recorded in any case where we are unable to process the transaction import. A warning will typically be recorded to the transaction import if we believe a piece of information should be brought to the user’s attention. We’ll still process the import after the user has confirmed, even with warnings.

Lastly, info is recorded to the transaction import when we believe the information being recorded is useful overview data, for example, number of transactions to be processed.

Error list

This list containts all the types of errors you can expect to see. This does not mean the ‘message’ will always be the same for every error of this type.

"errorDetails": [
    {
        "severity": "error",
        "code": "ValidationError",
        "message": "One or more fields were missing, or failed to match the required specification",
        "target": "unknown"
    }
],

A validation error is typically seen when 1 or more fields in the supplied data or file failed to meet the specification.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "File format not supported",
        "target": "File"
    }
],

Processing errors are used for various reasons, an example would be if an unsupported file format was submitted.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "Failed to parse file",
        "target": "File"
    }
],

There was a problem parsing the file which was uploaded.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "TransactionImport has already been deleted",
        "target": "unknown"
    }
],

The error response if the DELETE endpoint is called on a transaction import that has already been deleted.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "Failed to create an S3 pre-signed POST URL",
        "target": "unknown"
    }
],

The type of error returned if there’s a problem with the S3 service when creating a pre-signed URL.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "Failed to get file from S3 bucket",
        "target": "unknown"
    }
],

Unable to GET file from S3 bucket.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "Failed to insert item into database",
        "target": "unknown"
    }
],

The type of DB error response. For example, unable to save a transaction import request to the DB (issue with DynamoDB).

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "This Batch is not currently accepting additional uploads of TransactionDetails and AccountDetails",
        "target": "unknown"
    }
],

This error will be returned if the status of the batch on PAPI is in any other status other than ‘accepting’.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "Failed to process Batch on Provider API",
        "target": "unknown"
    }
],

Something went wrong with PAPI processing the submitted batch of transactions. Another example would be if PAPI returned a 500 (Internal Server Error) status code to the connector.

"errorDetails": [
    {
        "severity": "error",
        "code": "AuthorizationError",
        "message": "The provided credentials are not valid for this request",
        "target": "unknown"
    }
],

A 401 AuthorizationError is returned if the credentials provided aren not valid for the request the user is trying to perform. For example, delete a transaction import which they’re not authorised to do so.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "No statementId found on the TransactionImport",
        "target": "unknown"
    }
],

A 409 will be returned if data cannot be found, for example a transaction import was not found with the provided ID.

"errorDetails": [
    {
        "severity": "error",
        "code": "ProcessingError",
        "message": "The TransactionImport is not in the correct state for this operation",
        "target": "unknown"
    }
],

A 409 will be returned if the status of a transaction import is not in a valid status when the import is confirmed.

{
    status: 429,
    code: 'TooManyRequests',
    message: 'Too many requests'
}

A 429 is returned if the user has exceeded the rate limit for the API Lambda. DOS prevention. This is not returned as errorDetails.

{
    status: 500,
    code: 'InternalServerError',
    message: 'An error occurred while processing the request'
}

A standard internal server error. Typically used when something went wrong unexpectedly and the error could not be handled.

"errorDetails": [
    {
        "severity": "warn",
        "message": "found transactions for accounts not requested for this import",
        "ignoredTransactions": "16"
    }
],

Warning messages will be used when the information could be useful to the end user and might impact their decision to proceed with the import. For example, we display the number of ignored transactions after submitting a batch to PAPI.

"errorDetails": [
    {
        "severity": "info",
        "message": "file deleted from S3"
    },
    {
        "severity": "info",
        "message": "batch deleted from providerAPI"
    },
    {
        "severity": "info",
        "message": "deleted TransactionImport"
    }
],

Info messages are used and added to the errorDetails object to show key milestones throughout the transaction import. This examples show the array of messages you’d typically see when deleting a transaction import.

"errorDetails": [
    {
        "severity": "info",
        "message": "JSON.parse(data)"
    },
    {
        "severity": "info",
        "message": "data in PAPI format, nothing to validate"
    },
    {
        "severity": "info",
        "message": "data in PAPI format, nothing to transform"
    }
],

The info returned to the user if they submitted a file that’s already formatted and transformed for PAPI.

"errorDetails": [
    {
        "severity": "warn",
        "code": "PossibleDuplicatedTransactions",
        "message": "One or more transactions matching imported transaction dates were found on your account",
        "target": bankAccountId,
        "details": [
            "2020-03-11": 20,
            '2019-01-01': 3
        ]
    }
],

This highlights a potential duplicate transaction. This will appear as a warning in the errorDetails object. The ‘details’ section of the warning provides information around dates which transactions are already held on the bank account.

Transactions will be broken down by day for the time period provided in the file. For example, the above file may have contained transactions dated between 2018-12-31 and 2020-12-31, and the bank account already has transactions logged for the 2 dates given.