Error handling and retry strategy

Understand which errors to retry, which require fixes, and what Sovos handles automatically.

When you submit documents through the Sovos API, you may receive error responses. Each error falls into one of three categories:


Category name	Code range	Description	Retry responsibility	General action
Client	400-404, 409, 422	Problems with your request data. Fix the issue before resubmitting	None; fix the request	Inspect `errors[].subCode`, correct the problem, resubmit
Network	408, 429	Timeout or rate limiting. Your system should retry after waiting	Your system	Wait at least 60 seconds, then retry
Server	500-504	Sovos or tax authority system issues. Sovos automatically retries these errors	Sovos (automatic)	Continue polling; do not retry manually

The following topics explain the error response format, specific error codes and subcodes, automatic retry behavior, and troubleshooting steps for each error category.

HTTP status codes and retry rules

Sovos uses standard HTTP response codes. Understanding which codes to retry and which require fixes prevents duplicate submissions and ensures efficient error recovery.


Code	Name	Category	Retry?	Action
200	OK	Success	N/A	Process response data
202	Accepted	Success	N/A	Poll for completion using `jobState`
400	Bad request	Client	Never	Check for validation errors in your request. If no validation errors are found, contact Sovos support
401	Unauthorized	Auth	Never	Verify that your API key or token is valid
403	Forbidden	Auth	Never	Check product assignments and permissions
404	Not found	Client	Never	Verify the `documentId` and endpoint URL
408	Request timeout	Network	Yes	Wait 60 or more seconds, then retry the request
409	Conflict	Client	Never	Check for duplicate submission
422	Unprocessable entity	Client	Never	Fix business rule violations
429	Too many requests	Network	Yes	Wait 60 or more seconds (check the `Retry-After` header), then retry
500	Internal server error	Server	Auto	Sovos retries automatically. Continue polling
501	Not implemented	Server	Auto	Sovos retries automatically. Continue polling
502	Bad gateway	Server	Auto	Sovos retries automatically. Continue polling
503	Service unavailable	Server	Auto	Sovos retries automatically. Continue polling
504	Gateway timeout	Server	Auto	Sovos retries automatically. Continue polling

Error categories

Client errors (400-404, 409, 422) - Problems with your request data. Fix the problem before resubmitting.
Network errors (408, 429) - Timeout or rate limiting. Your system should retry after waiting.
Server errors (500-504) - Sovos or tax authority system problems. Sovos automatically retries these errors.

Error response structure

All error responses follow a consistent JSON structure that includes the HTTP status code, error messages, and subcodes for programmatic handling.

The following example shows a typical error response:

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

Key fields


Field	Type	Description
`timestamp`	Integer	Unix time stamp in milliseconds when the error was generated on the server.
`status`	Integer	HTTP status code. Determines error category and retry responsibility.
`success`	Boolean	Always `false` for error responses.
`message`	String	Human-readable summary of the error.
`errors[].subCode`	String	Machine-readable error type. Use this for programmatic handling.
`errors[].message`	String	Detailed description of the specific error.

Error subcodes

Subcodes provide more specific error categorization than HTTP status codes alone, enabling programmatic error handling.

For example, HTTP 400 is a generic "Bad Request" error. Subcodes tell you specifically what went wrong:

invalidParameter - An invalid field value. Fix the field.
missingParameter - A required field is missing. Add the field.
document.malformed - The XML structure is invalid. Fix the document structure.

Common subcodes


Subcode	What it means	Programmatic action
`invalidParameter`	Invalid field value in request	Validate input data.
`missingParameter`	Required field is missing	Add the missing field.
`document.malformed`	XML structure is invalid	Fix the document structure.
`authorization.invalidCredentials`	Invalid API credentials	Refresh the authentication token.
`internalServerError`	System error	Monitor for automatic retry.

Use subcodes for automation

The following example shows how to handle subcodes programmatically:

if (response.errors && response.errors.length > 0) {
  const subCode = response.errors[0].subCode

  switch(subCode) {
    case 'invalidParameter':
    case 'missingParameter':
      alertValidationTeam(response)
      break

    case 'authorization.invalidCredentials':
      refreshAuthToken()
      break

    case 'internalServerError':
      monitorRetryStatus(documentId)
      break
  }
}

What Sovos retries automatically

Sovos automatically retries HTTP 500-504 errors when communicating with tax authorities. You do not need to implement retry logic for these errors.

Important:

Retry parameters are country-specific. Maximum attempts, delay schedules, and total duration vary by country. Your country-specific implementation guide covers the exact retry parameters.

What Sovos does

When Sovos detects a retryable error from a tax authority, the following process occurs:

Sovos detects the retryable error from the tax authority.
Sovos raises a TaxAuthorityUnavailable event.
Sovos retries the transmission with the configured delay schedule.
Sovos continues until the transmission succeeds or the maximum number of attempts is reached.

Your responsibility

While Sovos handles the retry logic, you are responsible for the following actions:

Continue polling the transmission endpoint.
Pass the jobState parameter from each response to the next poll.
Monitor for the final status (success or failure).

Troubleshooting by HTTP code

Use the following troubleshooting steps based on the HTTP status code you receive.

400-404 and 422: Fix your request

Review errors[].subCode and errors[].message.
Check SCIInternalValidation for field-specific details.
Fix the identified problems in your document.
Resubmit as a new document.
If HTTP 400 persists with no validation errors, contact Sovos support.

408 and 429: Wait and retry

Wait 60 or more seconds.
Check the Retry-After header if present (429).
Retry the original request.
Implement throttling if you receive frequent 429 responses.

500-504: Monitor automatic retry

Continue polling with jobState.
Sovos retries automatically.
Check the tax authority status page if the error persists.
Contact support if the error exceeds the maximum retry duration.

401: Re-authenticate

Verify that your API credentials are correct.
Check if the token has expired (typically one hour).
Get a new token.
Retry the request with the new token.

403: Check permissions

Verify that the product is assigned to your company.
Check your role permissions.
Contact your administrator if you need access.

When contacting support

When you contact support, provide the following information:

documentId
correlationId (the x-correlationId header value)
Time stamp
Complete error response
Steps you attempted to resolve the problem

How can we help?