When CertCapture sends exemption certificate data to AvaTax, incomplete or incorrect information can cause API errors that prevent certificates from being applied to transactions. This article explains how to identify and fix common CertCapture API errors.
Quick answer
- API errors appear on the History tab of the exemption certificate in CertCapture when certificate or customer data is missing or invalid.
- Most errors require you to edit the certificate Details tab or the linked customer Details tab to add or correct the missing field.
- Run a Failed API Calls report under Reports > Logistics Reports to see all certificates with unresolved errors across your account.
Where to find API errors in CertCapture
API errors are logged on the History tab of the exemption certificate. To view the error message, go to the certificate in CertCapture and select the History tab.
To see all certificates with unresolved API errors:
- In CertCapture, go to Reports > Logistics Reports.
- Select Failed API Calls from the list.
- Enter a date range and select Run Report.
- Select Email Report to set up a scheduled report, or select Export Report to download a spreadsheet.
Common CertCapture API error messages and how to fix them
| Error message | What it means | How to fix it |
|---|---|---|
| Reason Code X isn't exempt in region(s): XX. (Invalid ExemptReasonId and region combination) | The exemption reason is invalid for one or more regions on a multijurisdictional certificate. | Go to the certificate Details tab and select Edit to choose a new exemption reason. See the exempt reason matrix for the U.S. and Canada to confirm the reason is valid for all regions. If no valid reason exists, revalidate the certificate excluding the listed regions. |
| Certificate exempt reason doesn't exist in AvaTaxCalcApi. | The exemption reason is not available in AvaTax. | Go to the certificate Details tab and select Edit to enter a new exemption reason. See the exempt reason matrix for the U.S. and Canada for the full list. |
| DocumentRefNo is required. (This value must be specified.) | The certificate is a single-use certificate but does not have a PO number. | Go to the certificate Details tab and select Add PO Number. |
| CustomerName is required. (This value must be specified.) | The Customer Name field is empty for at least one linked customer. | Go to the certificate Customers tab, select the customer number, go to the customer Details tab, and select Edit to enter the customer name. |
| The certificate customer(customer number) doesn't contain an address. | The Address Line 1 field is empty for the listed customer. | Go to the customer Details tab for each customer and select Edit to enter the street address. |
| Address1 length must be between 1 and 50 characters. | The Address Line 1 field exceeds 50 characters. | Go to the certificate Customers tab to find the customer, go to the customer Details tab, and select Edit to shorten the street address to 50 characters or fewer. |
| The Address Line 2 field is too long for at least one of the customers linked to the certificate. | The Address Line 2 field exceeds 50 characters. | Go to the certificate Customers tab to find the customer, go to the customer Details tab, and select Edit to shorten the Address Line 2 field to 50 characters or fewer. |
| The certificate customer(customer number) doesn't contain a city. | The City field is empty for the listed customer. | Go to the customer Details tab for each customer and select Edit to enter the city name. |
| Region is required. (This value must be specified.) | The Region field is empty for a linked customer. | Go to the certificate Customers tab to find the customer missing a state or province, select the customer number, go to the customer Details tab, and select Edit to choose the state or province. |
| The certificate customer(customer number) doesn't contain a zip. | The ZIP field is empty for the listed customer. | Go to the customer Details tab for each customer and select Edit to enter the ZIP Code. |
| The certificate customer(customer number) isn't associated to a country. | The Country field is empty for the listed customer. | Go to the customer Details tab for each customer and select Edit to enter the country name. |
| Certificate record couldn't be found or didn't meet send credentials. | The certificate's effective date is in the future, or another condition prevents the API call. | Go to the certificate Details tab and select Edit to change the effective date. If the future date is intentional, no action is needed; CertCapture will send the API call on the effective date. If the certificate is not future-dated, open a support case. |
| ExemptCertDetail.IdNo is required. | The Tax ID field is empty. A Tax ID is required for exemption certificates in SST states. | Go to the certificate Details tab and select Edit to enter a tax ID. |
Expert tip: Check that API errors disappear after fixing
After you correct certificate or customer data, return to the certificate History tab to confirm the error is gone. CertCapture automatically retries the API call after you save changes, so a successful retry means the certificate data is now flowing to AvaTax.
How Galvix can help with exemption certificate management
Tracking down missing customer addresses, fixing invalid exemption reasons across multiple jurisdictions, and monitoring API error logs requires time you may not have. Each correction means editing certificate details, updating customer records, and checking the History tab to confirm the retry succeeded.
Galvix's compliance team handles exemption certificate management from start to finish. That includes requesting certificates from exempt buyers, verifying that all required fields are complete and accurate, storing them, and following up before they expire. You won't need to troubleshoot API errors or maintain certificate records yourself.
If managing exemption certificates is pulling you away from other work, see how Galvix can take it off your plate. Book a demo.
FAQ
Can I fix multiple API errors at once by updating customer data in bulk?
Yes. If multiple certificates share the same customer record and the same data is missing, editing the customer once will resolve the error for all linked certificates. To update many customers at once, use the CertCapture import template.
Why does the error say the exemption reason is invalid for certain regions?
For multi-jurisdictional certificates, the exemption reason must be valid in all regions listed. Some exemption reasons apply only to specific states or provinces. If you cannot find a valid reason for all regions, revalidate the certificate and exclude the regions where the reason does not apply.
What does it mean if the error says the certificate record couldn't be found?
This error typically means the certificate has an effective date in the future. CertCapture will not send the API call until that date. If the certificate is not future-dated and you still see this error, contact Avalara support.
Where can I find the exempt reason matrix referenced in the error fixes?
The exempt reason matrix for the U.S. and Canada is available in Avalara's documentation. You can access it through the CertCapture knowledge base or by searching for "exempt reason matrix" in Avalara's help center.
