Sovos.com Contact Support

Filing

VAT Filing

Error handling

Use HTTP status codes and error details to understand why a request failed and what to do next.

The External Partner API uses a two-step approach to diagnose errors:

  1. Checks status to identify problem category.

  2. Checks subCode in the errors array to identify the specific cause and decide how to handle it in your code.

Note:

See API concepts for key terms used on this page.

Error objects

Each item in the errors array is an ErrorItem object with two fields.

Field Type Description
message string Human-readable explanation of the problem.
subCode string Machine-readable code for branching logic and support.

Use subCode in your error-handling code. It's stable across API versions. Use message for logging and debugging.

Note:

401 and 403 responses don't use the data field from the standard success and 400/404/500 shape.use a slightly different envelope.

How to read an error response

Step 1 - First check
Check success first before reading the rest of the response. If it's false, skip data and go straight to errors.
Step 2 - Branch your error-handling logic
Use status to decide how your code responds. For example: retry on 500, refresh your token on 401.
Step 3 - Read the errors array
Iterate the errors array. Use subCode for branching logic and message for logging. Ignore data on error.
Step 4 - Support call tracing
Include timestamp, uuid, and message in your support requests to help Sovos trace the call.
Note:

See API Responses.

HTTP status codes

Code Meaning What to do
200 Success Process the response.
400 Bad request

Your request failed validation. Check the errors array for details.

A common cause is trying to import data for a filing that's already in Complete status.
401 Unauthorized

Your token is missing, invalid, or expired. Refresh your token and retry.

The response has no data field.
403 Forbidden

Your token is valid, but you don't have permission for the resource or operation. Check errors[].subCode to identify the specific problem.

Don't retry without changing your token or request. The response has no data field.
404 Not found The resource doesn't exist, has no data, or isn't visible to your token. data is null.
500 Server error

An unexpected error occurred on the server. data is null, errors has at least one item. Retry using exponential backoff.

If the problem persists, contact Sovos support and include the uuid from the response.
400 Bad request

Your request failed validation. A common cause is trying to import transactions for a filing that's already in Complete status.

JSON 
{
        "success": false,
        "status": 400,
        "message": "Bad request",
        "timestamp": 1776333600000,
        "uuid": "a1b2c3d4-e5f6-7890-ab12-cdef34567890",
        "data": null,
        "errors": [
            {
            "message": "The filing is already complete. Transaction imports are not allowed.",
            "subCode": "IMPORT-400-FILING_COMPLETE"
            }
        ]
        }
401 and 403 authentication errors

A 401 means your token is missing, invalid, or expired. A 403 means your token is valid but you don't have permission for the resource or operation. Check your token and try again.

404 Not found

The resource doesn't exist or isn't visible to your token. Check that the ID in your request is correct.

JSON 
{
        "success": false,
        "status": 404,
        "message": "Filing not found",
        "timestamp": 1776333600000,
        "uuid": "e5f6a7b8-c9d0-1234-ef01-567890123456",
        "data": null,
        "errors": [
            {
            "message": "No filing exists for the given company and filing id",
            "subCode": "FILING-404"
            }
        ]
        }
Handling 500 errors
Any endpoint can return 500. Retry your request using exponential backoff. If the problem persists, contact Sovos support and include the uuid from the response to help trace the call.
Reading error details
Every error response uses the same envelope structure. Check the errors array for details. Each item includes a message and a subCode to help you identify the specific cause.

Known subcodes

subCode Status Cause
authorization.invalidCredentials 401 Missing, invalid, or expired token.
authorization.forbidden 403 Authenticated but not authorized.
FILING-404 404 Filing not found, no filings match the filters, or no result files available.
IMPORT-404 404 Import not found, no imports exist for the company, or no result files available.
IMPORT-400-FILING_COMPLETE 400 The filing is already COMPLETE. You can't import transactions for a closed period.
VAL-400-12 400 metadata.fileSize must be greater than zero.
VAL-400-03 400 metadata.importProfileId must be a valid UUID.
SRVR-500 500 Unexpected server error.
Filing.CompanyNotFound 400 The company.id in the request body doesn't match the company context in your Bearer token.

Errors returned to the client

Error code Description Error returned to the client
Import.ProfileNotFound No import profile could be resolved for the account. An error occurred while importing the file. Import Profile not found.
Import.AccountInactiveOrMissing Account missing or inactive. Authenticated Account is not active or not found.
Import.FileImportProcessFailed Exception during processing in dashboard JSON FileImport. An error occurred while importing the file. Verify it is in the correct format.
Import.DuplicateAdministrationCompany Duplicate administration + company in the payload after mapping.

Can't import file. The uploaded file contains duplicate administrations with (administration code and company code).

Edit the uploaded file and remove or change the duplicate administrations.
Import.ColumnMappingMissin Mapped profile column missing from the JSON-derived row.

Row n: Field field has no mapping.

Make sure the import profile column is present in the imported file or select "Import no columns" as null.
Import.RequiredColumnMissingAfterMapping Required column missing after JSON→table mapping.

Row n: Column field: The uploaded file is missing the specified column and could not be mapped.

Edit the file and add the missing column or select "Import no columns" as null.
Import.RequiredFieldEmpty Required field empty for that row.

Row n: The uploaded file is missing the required data for column field.

Edit the file and add the missing data.
Import.InvalidCurrencyFormat Currency format invalid for that field.

Row n: Invalid format value in column column.

Format currency with a comma as the thousand separator, and a decimal point before the cents (for example 400,755.52).
Import.InvalidDateFormat Date/datetime format invalid.

Row n: Invalid format value in column column.

Check the allowed date formats specified in the import profile used, for example: dd/mm/yyyy.
Import.InvalidNumericFormat Numeric format invalid. Row n: Invalid format value in column column. Only numeric data is allowed.
Import.FieldTypeConversionFailed Value can't be converted to the target type. Row n: Error converting document column column to field field, field value value can't be converted into datatype type.
Import.MetadataInvalidCurrencyFormat Metadata currency format invalid.

Invalid format for value in metadata field field.

Check the allowed currency format on the import profile used, for example: 400,755.52.
Import.MetadataInvalidDateFormat Metadata date format invalid.

Invalid format value in metadata field field.

Check the allowed date formats specified in the import profile used, for example: dd/mm/yyyy.
Import.MetadataInvalidNumericFormat Metadata numeric format invalid. Invalid format value in metadata field field. Only numeric data is allowed.
Import.MetadataTypeConversionFailed Metadata conversion failed. Error converting metadata field field, field value value can't be converted into datatype type.
Import.TranslationNotFound Translation lookup returned no row.

Row n: The value value in field field isn't found in the translation table, which is used to transform information in this field from one value into another.

Edit the uploaded file to match a value in the table, or update the translation table.
Import.TranslationAmbiguous Translation lookup returned multiple rows.

Row n: The value value in field field matches multiple rows in translation table, which is used to transform information in this field from one value into another.

Edit the imported file or translation table to remove the duplication.
Import.InvalidRowData Generic invalid-data path after mapping. Row n: Invalid data. This data can't be processed. Edit the uploaded file and correct the data.
Import.AdministrationUnresolved Administration can't be resolved from the mapped data.

Row n: Can't attach to Administration value because it is either missing an administration code or it isn't attached to the VAT Code or the Company Code.

Verify that you have all codes in your uploaded file.
Import.DataAccuracyRuleFailed Data accuracy rule failed. (Full message from rule)
Import.RequiredJsonMappingFieldMissing Missing required field for JSON/import mapping. Row n: (dynamic text)
Import.ImportPolicyViolation Blocked by account policy. Row n: InvoiceNumber: value . This invoice can't be imported due to the restrictions provided by your account administrator.
Import.DateYearBelowMinimum Date year before 1753. Row: n, "value" - Invalid date (min year: 1753). Check and correct all date fields.
VAT Filing Developer Implementation API Reference

Last updated: July 28, 2026