Filing

Service status

Check whether the External Partner API is available, so you know when to send filings and imports and when to wait.

The /v1/indirect-tax/vat-filing/status endpoint returns the current service status of the External Partner API.

Note:

Service status uses a bearer token as the authentication method. See Authentication.

Use cases

Check the service status when you:

  • Prepare to send filings or imports.

  • Set up an uptime monitor or health dashboard.

  • Start your integration and need to confirm that the API is ready.

Service status codes

The /v1/indirect-tax/vat-filing/status returns one of three values in the status field. Each value maps to an HTTP response code.

Status Meaning HTTP code What to do
Healthy The service is working as expected. 200 OK

Keep sending requests as usual

.
Degraded The service can still handle core API operations. 200 OK
  1. Keep sending requests.

  2. Check the status again at your next scheduled check.

Stop only if the service returns 503.

Unhealthy The service can't reliably process requests. 503 Service unavailable
  1. Stop sending filings and imports.

  2. Retry using exponential backoff.

See Best practices for the wait times.

Tip:

Healthy and Degraded both return 200 OK, so read the status field to tell them apart. For the reason, see Frequently asked questions.

Note:

If a request times out after about 15 seconds or fails with a connection error, treat it as Unhealthy. A 401 or 403 response isn't a service status. It has no status field and doesn't mean the service is down.

Resources

The service status endpoint uses these servers and paths.

Environment Server Path
Production https://api.sovos.com /v1/indirect-tax/vat-filing/status
User Acceptance Testing (UAT) https://api-test.sovos.com /v1/indirect-tax/vat-filing/status

Get a service status

GET /v1/indirect-tax/vat-filing/status

Use this endpoint to check whether the External Partner API is available. It works for uptime monitors, health dashboards, and readiness checks in your own code. The request is read-only.

Tip:

Send the request to the address for your environment. See Resources.

Step 1 - Send a GET request with your bearer token

Add your bearer token to the Authorization header. The request has no body and no query parameters.

CODE
curl -i "https://api.sovos.com/v1/indirect-tax/vat-filing/status" \
  -H "Authorization: Bearer <access_token>"
Note:

For more information about bearer tokens, see Authentication.

Step 2 - Review the response

The endpoint returns the same two fields for every service status.

Field Type Required Description
status string Yes The overall service status. In a 200 response, the value is Healthy or Degraded. Sovos returns Unhealthy only with a 503.
totalDuration string Yes The time taken to evaluate the health status, in the format hh:mm:ss.fffffff. This value is informational only.

Example response 200:

JSON
{
  "status": "Healthy",
  "totalDuration": "00:00:00.0065176"
}

Example response 200 when the status is Degraded:

JSON
{
  "status": "Degraded",
  "totalDuration": "00:00:00.0148230"
}

Example response 503:

JSON
{
  "status": "Unhealthy",
  "totalDuration": "00:00:00.0312045"
}

Each 200 and 503 response includes the Cache-Control: no-store, no-cache header. This header prevents caching, so each check returns the current status.

Important:

This response doesn't use the standard envelope. It has no success, data, or errors fields.

Step 3 - Act on the status and check again

For more information about checking the service status, see Best practices.

Response codes

200
Returns the service status. The status is Healthy or Degraded.
401

Unauthorized. Your token is missing, expired, or invalid. Refresh the token and retry. This is a problem with your token, not a service outage.

Example response (401):

JSON
{
  "fault": {
    "faultstring": "Access Token expired",
    "detail": {
      "errorcode": "keymanagement.service.access_token_expired"
    }
  }
}
403

Forbidden. Your token is valid, but it doesn't have permission for this resource. If you need permissions, contact Sovos if you need access. This isn't a service outage.

503

Service unavailable. The service can't reliably process requests. Pause or retry using exponential backoff. Wait five seconds, then 10 seconds, then 30 seconds, then 60 seconds. Don't submit filings or imports while the service returns 503.