Sovos.com Contact Support

e-invoicing

Indirect Tax API

HTTP status codes

Sovos uses standard HTTP response codes to indicate the outcome of API requests, ranging from successful operations to client-side and server-side errors.

HTTP response codes fall into the following categories:

200 range
These codes mean success.
400 range
These codes suggest a client-side error due to the information provided. This could be a required parameter that is missing or an error in the Standard Business Document.
500 range codes
Indicate issues related to the Sovos’ servers, governmental credentials, or the network.

These response codes are incorporated into each JSON response message, which also includes a description, a Unix timestamp, and potentially any output files as part of an application response. If there are errors, the response will also include a standardized subCode explaining what to do to fix them.

Indirect Tax API supports the following HTTP status codes:

HTTP Status Code Name Description
200 OK The API request was received and processed successfully (synchronous transaction).
202 Accepted The API request was received and is in progress (asynchronous transaction).
207 Multi-Status Multiple operations have occurred. See the status of each operation in the response body.
400 Bad Request The server could not accept the request. This is often because the request missed a required parameter.
401 Unauthorized No valid API key or token provided.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
405 Method Not Allowed The server does not allow the executed method.
408 Request Timeout The server didn't receive a request from the client within an acceptable time limit.
409 Conflict The request conflicts with another request, often due to duplicate documents.
429 Too Many Requests The number of requests sent exceeds the API server's rate limit (number of calls per minute).
500 Internal Server Error Something went wrong on Sovos' end.
501 Not Implemented The requested functionality has not yet been implemented.
503 Service Unavailable The server is currently overloaded with requests, out of resources, or is currently under maintenance.
504 Gateway Timeout The request was timed out.

Handle HTTP errors

Because all error codes in the 400 range represent client errors, you must fix them before making another API request. The only exceptions are error codes 408 and 429, where a wait time of at least one minute is recommended before retrying.

For an error code within the 500 range, which represents server errors, you must wait one minute after the initial error before sending the request again. If the issue persists, continue to retry the request every five minutes for up to an hour. If the error remains unresolved, reach out to Sovos' Support team for assistance. The only exception is error code 501. In this case, there's no need to retry, because the error indicates that the functionality has not been implemented yet.

Error responses

If there's an error, the JSON response always contains the same elements. You can use the status and subCode elements to create an automated error-handling process. You can also use the message element to get a human-readable description of the error.

The following information is included in the response schema:

Response schema Type # Description
timestamp number 1..1 Unix timestamp from when the request was executed.
status number 1..1 The HTTP status code.
success Boolean 1..1 Shows if the request was successful. In case of errors, it will always be "false".
message string 1..1 A human-readable message describing the error.
errors message string 1..1 Properties related to error data.
subCode string 1..1 The error's subcode.

Available subcodes

These are the possible HTTP status codes and the corresponding subCode that the Indirect Tax API can return:

HTTP Status Code subCode
300 document.signature.valid
301 document.signature.invalid
302 document.signature.signerInvalid
400 invalidParameter
400 missingParameter
400 parseError
400 operationNotImplemented
400 countryNotSupported
400 document.error
400 document.invalidParameter
400 document.malformed
400 document.documentDataInvalid
400 document.invalidBusinessProcess
400 document.auditDetailsNotSupported
400 document.noApplicableKeyReference
400 document.secondFactorNeeded
400 document.auxiliaryFunctionClientFailure
400 document.unsupportedAuxiliaryFunction
400 document.asyncBehaviorRequired
400 document.noApplicableIndividualKey
401 authorization.invalidCredentials
403 notSupported
403 config.companyNotRegistered
403 config.companyAlreadyRegistered
403 config.companyNotEnabled
403 config.companyAlreadyEnabled
403 config.companyClosed
403 config.companyLocked
403 config.companyNotLocked
403 config.branchNotRegistered
403 config.branchAlreadyRegistered
403 config.branchNotSpecified
403 config.countryNotEnabled
403 config.countryOfEstablishmentAlreadySet
403 config.certificateAndKeyMismatch
403 config.certificateAlreadyExists
403 config.certificateNotTimeValid
403 config.invalidPassword
403 config.ReferentialIntegrityFailure
403 document.branchNotRegistered
403 document.branchNotSpecified
403 document.countryNotEnabled
403 document.storageLimitExceeded
403 document.invoiceExpired
403 document.counterpartyFailure
403 document.blocked
403 document.unusableIndividualKey
403 document.noPin
403 document.wrongPin
403 document.certificateNotTimeValid
403 document.invalidPassword
403 document.workflowNotSupported
404 notFound
404 config.companyNotFound
404 config.IdentityProviderNotFound
404 config.notFound
404 document.notFound
405 httpMethodNotAllowed
409 duplicated
409 idempotency.inProgress
409 idempotency.doesNotMatch
409 document.operationUniquenessViolation
500 system.error
501 proxyNotImplemented
503 serviceUnavailable
504 timeout

Response fields

Fields that can be part of the responses and sometimes part of the request parameters:

productId
This is the ID of a product within the Sovos system. Sovos defines different products for each country and, if necessary, different products within the same country. A company must have at least one product, but can have multiple products.
appPrefix
This is the application prefix, which is for internal Sovos use only. This field can be ignored.

Samples

JSON 
{
    "timestamp": 1634217741305,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "a21b76210c0b6044690bb450d3f3bea354d1"
    }
}
JSON 
{
    "timestamp": 1639056915485,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 100,
            "totalPages": 1,
            "totalEntries": 2
        },
        "notifications": [
            {
                "createdDate": "1638473970231",
                "metadata": {
                    "productId": "NFe",
                    "documentId": "LXNvdm9zfDk5OTl8NTV8MTMxNXwxMTQ0MDM0MQ==",
                    "erpDocumentId": "11111",
                    "erpSystemId": "UAT800",
                    "processType": "0",
                    "taxId": "06158643000144",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "Smart DF-e",
                "notificationId": 13248873,
                "content": "PEF...c2U+"
            },
            {
                "createdDate": "1638475005999",
                "metadata": {
                    "productId": "NFe",
                    "documentId": "LXNvdm9zfDk5OTl8NTV8MTMxNnwxMTg2OTgyOQ==",
                    "erpDocumentId": "00001",
                    "erpSystemId": "UAT800",
                    "processType": "0",
                    "taxId": "06158643000144",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "Smart DF-e",
                "notificationId": 13250178,
                "content": "PEF...c2U+"
            }
        ]
    }
}
JSON 
{
    "timestamp": 1634217579717,
    "status": 401,
    "success": false,
    "message": "Unauthorized",
    "errors": [
        {
            "message": "The request requires user authentication.",
            "subCode": "authorization.invalidCredentials"
        }
    ]
}
Indirect Tax API

Last updated: October 1, 2026