HTTP status error codes

The API uses standard HTTP status codes, including:

400 Bad Request—The request is invalid. This status can also indicate a business error. Review the error details for more information.
401 Unauthorized—The request does not include valid authentication credentials.
500 Internal Server Error—The operation should be retried later. If the error persists, contact Support.

Error information in responses

Whenever possible, the API returns an application/json response that includes error information, such as:

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

Each error includes a type that identifies the error category and a message that provides information.

Error types

The following table lists the error types that can appear in API responses:

Error type	Retry	Description
`schema-validation-failed`	No	The request does not meet the formal requirements of the message, such as when a required field is missing.
`data-validation-failed`	No	The data values do not meet business requirements, such as when the request contains an unknown currency code.
`resource-not-found`	Depends	The requested resource was not found. In some cases, such as back-to-back transactions generated in the background, retrying after a short delay might resolve the error.
`general-persistence-failure`	Yes	The data was not persisted successfully. The API architecture is designed to prevent this error by eliminating a single point of failure for transaction storage. Other operations that require a single centralized resource and are not part of the online sales process, such as transaction confirmation, can also return this error. Retry the operation after a short delay. See General Persistence Error.
`external-unique-id-already-exists\|refund-unique-reference-already-exists`	No	The unique identifier of the object that the API call is attempting to store already exists. The object was most likely stored by a previous call, and the error was raised when the request was retried.
`resource-usage-exceeded`	Yes (after delay)	The account is using too much of a given resource. Implement a back-off algorithm and retry the request after a short delay.
`external-system-error`	Yes	The external system returned an error, preventing the API from generating a proper response. For VAT/GST number validation, the system might raise a warning and still calculate tax, depending on the account settings.
`tax-country-not-detected`	No	The API could not determine a tax country for one or more lines because it did not receive enough information, usually location evidence. The response might still include tax-related information, including countries resolved from digital goods location evidence.
`required-fields-missing`	No (not without updating the field information)	The request requires additional information to proceed, usually address data. Consult the `required_fields` response field for details. If feasible, use this information to automatically manage required input fields.
`input-validation-failed`	No	The API could not parse the message.
`general-error`	Yes	Retry the operation later. If the error persists, contact your Vertex representative.
`api-authentication-failed`	No	Check your authentication credentials.