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:

Checks status to identify problem category.
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.

{
        "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.

{
        "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.

How can we help?

Error handling

Error objects

How to read an error response

HTTP status codes

Known subcodes

Errors returned to the client

sovos-footer