Data upload

Check filing status before importing

Before you start a transaction import, check that the target filing has a Preparation status. Filings in the In Progress or Complete status don't accept imports. If the filing is Complete, the API returns a 400 error with subcode IMPORT-400-FILING_COMPLETE.

Use GET /v1/indirect-tax/vat-filing/filings/{filingId} to confirm the status before calling the import endpoint.

Upload files before the time-limited URL expires

The upload URL the API returns when you start an import expires 10 minutes after the API returns it. If you miss the window, start a new import to get a fresh URL.

Don't store the upload URL for later use. Generate the URL immediately before you upload, and upload it right away.

Send the file upload directly to S3

The uploadUrl is a time-limited URL. You must send your PUT request directly to that URL, not to the Sovos API.

Don't include an Authorization header in the PUT request. The time-limited URL carries its own authentication. Adding an Authorization header causes the request to fail.

Set the Content-Type header to application/json and make sure the file size matches the metadata.fileSize value you sent in the POST request.

Processing and monitoring

After you upload your file, poll GET /v1/indirect-tax/vat-filing/transactions/imports/{importId} every 30 seconds to check the import status. Keep polling until the status reaches COMPLETED or FAILED.

Result files

Download URLs for result files expire 10 minutes after the API returns them. Each file has its own accessUrl and expirationDate. Check the expiration date before downloading, and call the result files endpoint again if a URL has expired.

Sovos deletes filing result files 30 days after the filing reaches Complete. Download and store any filing result files you need before that window closes.

Date formatting

The API uses two date formats, and mixing them up causes silent failures.

• Use YYYY-MM-DD (UTC) for filing period fields and date filter parameters: startDate, endDate, and dueDate.

• Use Unix epoch milliseconds (a 64-bit integer) for timestamp fields: The envelope timestamp and time-limited URL expirationDate fields.

Using the wrong format for date filter parameters returns an empty result instead of an error. Using the wrong format for timestamp fields causes upload failures.

Error handling and resilience

Handle errors with status codes and subcodes

Use a two-step approach when a request fails. First, check the status field to identify the category of the problem. Then check errors[].subCode to identify the specific cause and decide how to handle it in your code.

The subCode values are stable across API versions, so use them in your error-handling logic. Use the message field for logging and debugging only. For the full list of subcodes, see Error handling.

Retry 500 errors with exponential backoff

Any endpoint can return a 500 error when an unexpected upstream failure occurs. These errors aren't caused by your request. Retry with exponential backoff.

If the problem persists, contact Sovos support and include the uuid from the error response. Sovos uses this value to trace the call.

Refresh your token before it expires

Every request requires a valid Bearer token in the Authorization header. A missing, invalid, or expired token returns a 401 error.

Build token refresh into your integration so requests don't fail mid-workflow. If you get a 403 instead, your token is valid but doesn't have permission for the resource or operation. Check your OAuth scope and company context. For more information, see Authentication.