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.
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 |
Stop only if the service returns 503. |
Unhealthy |
The service can't reliably process requests. | 503 Service unavailable |
See Best practices for the wait times. |
Healthy and Degraded both return 200 OK, so read the status field to tell them apart. For the reason, see Frequently asked questions.
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.
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
Authorizationheader. The request has no body and no query parameters.CODEcurl -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 statusstring Yes The overall service status. In a 200 response, the value is HealthyorDegraded. Sovos returnsUnhealthyonly with a 503.totalDurationstring 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-cacheheader. 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, orerrorsfields. - 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
HealthyorDegraded. - 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.
