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

{
    "timestamp": 1634217741305,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "a21b76210c0b6044690bb450d3f3bea354d1"
    }
}

{
    "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+"
            }
        ]
    }
}

{
    "timestamp": 1634217579717,
    "status": 401,
    "success": false,
    "message": "Unauthorized",
    "errors": [
        {
            "message": "The request requires user authentication.",
            "subCode": "authorization.invalidCredentials"
        }
    ]
}

Sovos Docs