Status and Error Codes

When CereTax receives an API request, a number of different HTTP status codes can be returned in the response depending on the original request. In general, 2xx codes indicate success. 4xxcodes indicate the request contained an input error (e.x., a required field was omitted, an invalid value was used, etc.).5xx codes indicate an error with the CereTax server.

Any response with a 4xx or 5xx status code will include an error message with details about the error conditions for that code. All Errors will be returned in an errorMessages object in the API response, and include the following fields:

Field	Description
`code`	4-digit numerical error code
`type`	specifies the type of error, ex. input, authentication, situs
`message`	a short description of the error
`summary`	a more detailed description of the error
`errors`	the specific fields or values that triggered the error (when applicable)

Invoice and lineItem errors will be returned under the impacted invoice or lineItem.

All other errors will be returned in the main response body.

The following are examples of different types of errors and their location:

{
    "invoice": {
        "invoiceNumber": "123",
        "totalTaxInvoice": 0,
        "lineItems": [
            {
                "lineId": "1",
                "totalTaxLine": 0,
                "taxes": [],
                "validateAddresses": null,
                "valid": true,
                "errorMessages": []
            }
        ]
    },
    "ksuid": "2EDOt60pwulsWvMc7RyGnza4EDg",
    "systemTraceAuditNumber": "123456",
    "errorMessages": [
        {
            "code": 2007,
            "type": "Input",
            "message": "Duplicate STAN Provided",
            "summary": "The systemTraceAuditNumber provided in your request has already been used. Please provide a unique value."
        }
    ]
}

{
    "invoice": {
        "invoiceNumber": "123",
        "totalTaxInvoice": 0,
        "lineItems": [
            {
                "lineId": "1",
                "totalTaxLine": 0,
                "taxes": [],
                "validateAddresses": null,
                "valid": true,
                "errorMessages": []
            }
        ], 
				"errorMessages": [
					{
						"code": 2002,
						"type": "Input",
						"message": "Missing Required Values",
						"summary": "Values for one or more required fields were not included in your API request.",
						"errors": {
							"businessType": "empty value"
						}
					}
				]		
    },
    "ksuid": "2EDOt60pwulsWvMc7RyGnza4EDg",
    "systemTraceAuditNumber": "123456"
}

{
    "invoice": {
        "invoiceNumber": "123",
        "totalTaxInvoice": 0,
        "lineItems": [
            {
                "lineId": "1",
                "totalTaxLine": 0,
                "taxes": [],
                "validateAddresses": [],
                "valid": false,
                "errorMessages": [
                    {
                        "code": 2002,
                        "type": "Input",
                        "message": "Missing Required Values",
                        "summary": "Values for one or more required fields were not included in your API request.",
                        "errors": {
                            "contentYear": "Please provide a value for content year./"
                        }
                    }
                ]
            }
        ]
    },
    "ksuid": "2E7yK0j7YTb4bFO0i6MGsq3v2az",
    "systemTraceAuditNumber": "2E7yK0j7YTb4bFO0i6MGsq3v2az"
}

"errorMessages": [
	{
		"code": "1001",
		"message": "Invalid API Key",
		"summary": "The API key that you used for authentication was not valid.",
		"type": "Authentication"
	}
]

📘
The following is the full list of error codes that can be returned by the CereTax APIs. This list will be updated as new error codes are introduced.

HTTP Status	code	type	message	summary
403	1001	Authentication	Invalid API Key	The API key that you used for authentication was not valid.
403	1002	Authentication	Missing Authentication Token	An authentication token was not provided in your API request
403	1003	Authentication	Authentication Failed	Unable to authenticate the user or account
422	2001	Input	Missing Required Fields	One or more required fields was not included in your API request
422	2002	Input	Missing Required Values	Values for one or more required fields were not included in your API request
422	2003	Input	Invalid Input Value	One or more of the fields you provided had an invalid value.
422	2004	Input	No Line Items Provided	A line item was not provided in your API request. At least one line item must be provided.
422	2005	Input	Duplicate Lines	The line Ids you provided were not unique. All line Ids must be unique within an invoice
422	2006	Input	Duplicate Invoice Number	The invoice number provided in your request conflicts with an existing invoice
422	2007	Input	Duplicate STAN Provided	The systemTraceAuditNumber provided in your request has already been used. Please provide a unique value.
422	2008	Input	Invalid transaction status	The transaction status used for this operation is not valid.
200	2009	Input	No applicable taxes found	No applicable taxes found for the PS Code, Customer Type, and Business Type combination included in the request.
422	2010	Input	Invalid Delivery Charges	The same delivery charge cannot be passed at both the invoice and lineItem level.
422	2011	Input	Invalid Delivery Charges	Delivery charges for shipping and handling must specified using the separate 'shipping' and 'handling' parameters OR the combined 'shippingAndHandling" parameter
422	2012	Input	Duplicate Customer	A customer record already exists with the provided customerId or customerAccount.
422	2013	Input	Duplicate Exemption	An exemption already exists for the provided exemptionId, customerAccount, and profileId.
422	2015	Input	Missing date range for report	At least one of the following date range combinations must be used: content year & month, compliance year & month, invoiceDateStart & invoiceDateEnd, vendorInvoiceDateStart & vendorInvoiceDateEnd
422	3001	Situs	Invalid Postal Code	One or more of the postal codes you provided was not valid.
422	3002	Situs	Invalid Address Input	One or more of the address inputs you provided was not valid or was incomplete
422	3003	Situs	Address Cannot Be Validated	One or more of the addresses you provided could not be validated. Please review the provided addresses.
422	4001	Formatting	Invalid Request Format	The format of your request was invalid
200	5000	Transaction	Cannot Reverse Unposted Transaction	The requested transaction has not been Posted. Only Posted transactions can be reversed.
500	5001	Transaction	Invalid Transaction Status Change	Transaction cannot be changed to the provided status.
500	9000	Internal	Internal Server Error	Internal Server Error