Skip to content
Developerhome

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 both 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 one or more fields within 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 above, there is a data validation error. The errors are as follows:

  • 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 twice.
  • 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 within the Transaction Import connector. 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 one 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 within the step function of the Transaction Import connector, if the Transaction Import isn’t 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 only returned in circumstances where a more useful error can’t be returned. Often meaning something unexpected occurred in the processing of the Transaction Import.


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

The above is returned when a Transaction Import can’t 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
    }
}

The above is returned by the API throttler, in the circumstance where too many requests have been 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 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 were 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 users attention, however, we will still process the Transaction Import after the user has confirmed, even with warnings. Finally, 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

Below is a list of 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 one or more fields within 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 of why the above error would be added to the Transaction Import, would be if PAPI returned a 500 (Internal Server Error) status code to the connector. The above is a more user friendly message that has more meaning on the Transaction Import.


"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’t 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 can not 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 isn’t in a valid status when the Transaction 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 isn’t 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 Transaction 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. Above is 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
        ]
    }
],

The above highlights a potential duplicate transaction, this will appear as a warning within the errorDetails object. The ‘details’ section of the warning provides information around dates which transactions are already held on the bank account. This transactions will be broken down by day for the time period provided within 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 two dates given above.