Troubleshooting Guide

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.

Calculate Tax

Error MessageCodeError Description
Invalid token400The 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 out400The 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" }400A 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" } 400This 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" } 400This can occur when the US Postal Code is not specified for a transaction.
{
"errors": [
"Couldn't determine user's country based on provided details."
]
}
400The request did not contain sufficient location evidence.

Store Transaction

Error MessageCodeDescription
Permissions denied.400The 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" } 400The 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" ] } 400The 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" } 400An 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."
]
}
400The request did not contain sufficient location evidence.

Refunds

Error MessageCodeDescription
"warnings": [ { "type": "refund-amount-too-high", "message": "Provided amount to be refunded is too high, trimming." } ] 200The 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." ] } 400You cannot refund the transaction because it has not been confirmed.
{ "errors": [ "Transaction line not found." ] } 400The line_key that is specified in the request is not valid and cannot be refunded.
{ "errors": [ "Please provide total amount as a number." ] } 400You 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." ] } 400The specified refund amount is negative and this is not allowed in this instance. It can be enabled by support for certain cases.