Handling Errors

This section details error codes and types.

HTTP Status error codes

The following table lists the standard HTTP status codes used by the API:

HTTP Response Status

Resolution

400
Bad Request

This error might be caused by the invalid JSON payload in the request.

It can also be caused by the business logic issue. Inspect the error details included in the response (if any) for further information.

401
Unauthorized

Ensure the x-marketplace-seller-token HTTP header was included in the request and was valid.

500
Internal Server Error

The operation should be retried later. If the error persists, support should be contacted.

Response error information

In most cases. the API returns an response with error information in the JSON format. For example:

{
    "errors": [
        {
            "type": "data-validation-failed",
            "message": "Could not assign seller data with code: GB-M2"
        }
    ]
}

This data structure contains error type (category) and message with additional details.

Error types

The following table lists the error types used in the API:

Error type

Retry

Comment

schema-validation-failed

No

This error means that the input request does not meet the formal criteria of the message, for example a field missing.

data-validation-failed

No

This error means that there is something wrong with the data values provided on a business level - for example unknown currency code.

resource-not-found

Depends

This error means that the request resource is not found. In some cases (e.g. back to back transactions generated in the background), it might be enough to just retry after a certain time.

general-persistence-failure

Yes

This error signifies that the data has not been persisted successfully. Taxamo API architecture is built specifically to prevent that by removing a single point of failure for transaction storage.

Other operations, which are requiring a single centralized resource and are not a part of the on-line sales process (such as transaction confirmation), can signify that error and they should be retried after a short delay in such a case.

external-unique-id-already-exists|refund-unique-reference-already-exists

No

This means that the unique id of an object that the API call is attempting to store already exists - most likely it was stored upon a previous call and the error is being raised upon retry.

resource-usage-exceeded

Yes (after delay)

This error signifies that this account is using too much of a given resource. The solution here is to implement a back-off algorithm and retry after a short delay.

external-system-error

Yes

This error can signify an issue raised when communicating with an external system, that prevents rendering a proper response.
In cases of VAT/GST number validation, the system might raise a warning and still calculate tax - depending on account settings.

tax-country-not-detected

No

This error signifies that there was not enough information (usually evidence) to determine a tax country for one or more lines. The response will contain some tax-related information anyway, including countries resolved from digital goods location evidence.

required-fields-missing

No (not without updating the field information)

This error means that more information is required to proceed with the request - usually address data.

Please consult the required_fields response field for details. These can be used to automatically manage requirement of the input fields if feasible.

input-validation-failed

No

This error means that the message could not have been parsed.

general-error

Yes

The operation should be retried later and if the error persists, support should be contacted.

api-authentication-failed

No

Check your authentication data.



If you need further help, contact support at https://www.vertexinc.com/en-gb/support-services/taxamo-customer-support.

Did this page help you?