You can use the information here to help you understand the error messages that can be generated by the API and how to correct them.

Overview

HTTP Status error codes

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
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.

Error Messages per Request

Calculate Tax

Error Message	Code	Error Description
`Invalid token`	400	The access token is not valid. You need to check that it is correct and acquire a valid one if not.
`Failed to communicate with O Series: Read timed out`	400	The connection to Vertex Oseries has timed out.
`{ "errors": [ "Validation failed: ", "{:transaction {:buyer_names disallowed-key}}" ], "nickname": "calculateTax", "validation_failures": { "transaction": { "buyer_names": "disallowed-key" } }, "error_code": "validation_error" }`	400	A field that is not allowed is included in the request's JSON. Remove these fields to correct the issue.
`{ "errors": [ "Could not assign proper TAX rate to a product." ], "error_code": "validation_error" }`	400	This error indicates that the service could not retrieve a tax rate. This can have one of multiple causes such as the following: If you have not specified the region in the request for Canada. No tax rate exists for the product type.
`{ "tax_required_fields": [ { "field_name": "invoice_address.postal_code" } ], "storage_required_fields": [], "errors": [ "Please provide invoice_address.postal_code." ], "is_delegated": false, "error_code": "missing_tax_required_fields" }`	400	This can occur when the US Postal Code is not specified for a transaction.
{ "errors": [ "Couldn't determine user's country based on provided details." ] }	400	The request did not contain sufficient location evidence.

Store Transaction

Error Message	Code	Description
`Permissions denied.`	400	The access token is not valid. You need to check that it is correct and acquire a valid one if not.
`{ "errors": [ "This external_unique_id already exists in this mode." ], "error_code": "validation_error" }`	400	The `external_unique_id` field that is specified in the request already exists and thus this request would create a duplicate, which is not allowed. You need to change the ID so it is unique.
`{ "errors": [ "Failed to communicate with O Series: Read timed out" ] }`	400	The connection with Vertex Oseries has timed out. This only applies to US transactions.
`{ "errors": [ "Validation failed: ", "{:transaction {:buyer_names disallowed-key}}" ], "nickname": "calculateTax", "validation_failures": { "transaction": { "buyer_names": "disallowed-key" } }, "error_code": "validation_error" } `	400	An incorrect field name exists in the JSON that is attached to the request. You need to replace it with a correct field name.
{ "errors": [ "Couldn't determine user's country based on provided details." ] }	400	The request did not contain sufficient location evidence.

Refunds

Error Message	Code	Description
`"warnings": [ { "type": "refund-amount-too-high", "message": "Provided amount to be refunded is too high, trimming." } ]`	200	The amount that is specified in the refund is too high, usually more than the original transaction. The refund is made up to the transaction value and processed.
`{ "errors": [ "Only confirmed transactions can be refunded." ] } `	400	You cannot refund the transaction because it has not been confirmed.
`{ "errors": [ "Transaction line not found." ] }`	400	The `line_key` that is specified in the request is not valid and cannot be refunded.
`{ "errors": [ "Please provide total amount as a number." ] }`	400	You need to specify the amount that is to be refunded. This is missing from the request.
`{ "errors": [ "Total refund for this line cannot be higher than a transaction line amount." ] }`	400	The specified refund amount is negative and this is not allowed in this instance. It can be enabled by support for certain cases.