Error Codes

This page is the catalogue of error codes and named error states you’ll encounter across Protect. For symptom-driven debugging see Troubleshooting; this page is the structured reference of every error string the product can show.

The error strings on this page reflect what Protect surfaces in the UI. Exact vendor-side strings can vary by integration and release.

API HTTP status codes

The ThreatAware API returns a JSON envelope of the form {"Success": false, "StatusCode": <code>, "Message": "<text>"} on errors. The HTTP status, the StatusCode field, and the human Message are all surfaced verbatim in API client integrations. Live-captured response shapes:

HTTP status	Trigger	Response body
`200`	Successful request	Request payload
`400`	Invalid API key value (e.g. `X-ThreatAware-ApiKey: BOGUS`)	`{"Success":false,"StatusCode":400,"Message":"Unexpected error occurred."}`
`400`	Unknown path under `/public-api/v1/`	`{"Success":false,"StatusCode":400,"Message":"Unexpected error occurred."}`
`401`	No `X-ThreatAware-ApiKey` header	`{"Success":false,"StatusCode":401,"Message":"No key was provided."}`
`403`	Token lacks scope for resource	Body varies; check Role Permissions
`404`	Resource ID not found (e.g. unknown device UUID)	Standard 404
`429`	Rate limit exceeded	Standard 429 — implement exponential backoff
`500`	Internal server error	Retry; if persistent, contact support
`502` / `503`	Upstream / temporary outage	Retry with backoff

The 400 vs 401 split is header presence versus header value. Send the header with garbage and you get 400 / "Unexpected error occurred."; omit the header entirely and you get 401 / "No key was provided.". Library defaults that strip empty headers will trip this distinction.

See API Reference → Response Codes for the canonical list and rate-limit handling guidance.

Sync errors (Integrations)

Integration sync state is surfaced on each integration card in Settings → Connections (the URL is /settings/connections). The connected state on a healthy card is the literal label CONNECTED; the Modify button beneath it opens a dialog with Enable Multi-Tenancy, Reauthorise, and Disconnect sections. Categories of sync error (structural — exact per-integration sync error strings vary by vendor):

Category	Typical surface	Resolution path
Auth expired	Card last-sync timestamp goes stale; vendor returns 401 on next cycle	Settings → Connections → card → Modify → Reauthorise → re-enter credentials or re-run OAuth
Auth revoked	Same as auth expired; vendor-side consent withdrawn	Re-grant consent on the vendor side, then Modify → Reauthorise
Insufficient scopes	Specific Vitals rows show stale data while the card stays CONNECTED	Add missing scopes vendor-side; for Microsoft see the Graph permissions guide
Rate-limited by vendor	Card stays CONNECTED but “Last synced” timestamps lengthen	Wait for the next cycle; reduce sync frequency if persistent
Vendor outage	Card last-sync stale, vendor returns 5xx	Check vendor status page; the next successful sync clears the state
PowerShell Relay offline	On-prem integrations only	RDP to relay server, verify the scheduled task and event log — see PowerShell Relay troubleshooting
TLS / certificate failure	PowerShell Relay integrations	Install a valid certificate, or enable Bypass Certificate Check on the integration

Action errors

Errors that surface in the Automation Log when an Action’s automation fires.

Category	Surface	Resolution path
Email delivery failed	Automation Log row → status `Failed`	Check recipient address validity; verify the recipient hasn’t filtered `noreply@threataware.com`
Webhook timeout	Automation Log row → status `Failed`, response code n/a	Endpoint slow or unreachable; verify the URL is reachable from ThreatAware egress; widen the destination timeout
Webhook 4xx response	Automation Log → response code visible	Endpoint rejected the payload — see Webhook Payload Reference for the expected shape
Webhook 5xx response	Automation Log → response code visible	Destination server error; the action will retry — see Webhook Payload Reference → Retries
Ticket creation failed	Automation Log → integration-specific error	Re-test the destination integration (ServiceNow / Halo / Jira); confirm credentials and table/queue permissions
Resolution criteria malformed	Action card warning	Open the Action → fix the criteria query — see Query Syntax

The webhook Test Webhook control reports the literal toast Successfully complete / The request Successfully completed even when the destination URL returns a 5xx response (verified live by pointing the test at https://httpbin.org/status/500). The Test Webhook flow validates that the request was dispatched, not that the destination accepted it. For end-to-end validation, save the Action, let it fire, and read the Automation Log on the Action detail page.

Integration auth errors

Specific errors during the Connect wizard and during re-authentication. The Reauthorise flow on a connected integration is a 4-step wizard (Step 1 of 4 → Step 4 of 4). Step 4 is the credentials form (label set varies by integration — e.g. ServiceNow exposes Platform URL, User ID, Password; the URL field placeholder is https://dev123456.service-now.com). The Step 4 button is Authorise. ServiceNow behaviour:

Submitting invalid credentials via the Reauthorise flow returns a Credentials saved confirmation in the dialog, followed by a Connect ServiceNow / ServiceNow is connecting, changes will appear soon toast on the connections page.
The Authorise step does not synchronously test credentials. Sync failure for bad credentials surfaces later on the integration card (stale last-sync timestamp) and in the next cycle’s audit log entries — not as an immediate wizard error.

Symptom in wizard	Likely cause
Wizard accepts credentials, card stays CONNECTED, last-sync never advances	Wrong credential format (extra whitespace, wrong field, expired secret) or scope missing — vendor-side failure on the first cycle
Wizard accepts credentials, card later returns to a degraded state	Same as above; the Reauthorise flow validates input format, not vendor-side acceptance
OAuth consent screen rejects	Insufficient privileges to consent (need Global Admin / equivalent); see Onboarding
Connection succeeds, no data after first sync	Service account lacks read scopes against the resources in question
PowerShell Relay `401 Unauthorised`	Wrong credentials, or the running account lacks permissions on the on-prem tool

Platform error states

These appear in the UI rather than as numeric codes. Vitals composite states (per the live device drawer):

State	Where it appears	Meaning
Healthy	Vitals row on a device drawer / Vitals grid	Control deployed, functioning, and configured correctly
Functioning	Vitals row for non-Required controls (identity / management)	Control reporting fresh data; no configuration check applied
Not Functioning	Vitals row	Control is deployed but isn’t reporting fresh telemetry — see Silent Failure and Vitals States
Misconfigured	Vitals row	Control is functioning but at least one configuration check fails — see Vitals Configuration
Not Deployed	Vitals row	Control isn’t present on this device
Required	Vitals row qualifier (separate label)	The control is in this device’s coverage scope — qualifies the state above
Detected / Not Detected Recently	Scanners (Lansweeper, Qualys, etc.)	Scanner has / has not seen the device in its recent window
CONNECTED	Integration card in Settings → Connections	The card’s literal badge text for a working integration

Full state reference: Vitals States.

In-product query parsing

The Device Explorer and Saved View query bars do not surface a parse error on malformed input. Invalid queries (e.g. tags:End-User AND AND OR ((() silently render No devices found rather than raising a syntax error. This was verified live by submitting the malformed string above to the Device Explorer command bar — the grid emptied to No devices found with no error toast or inline message. The same silent-zero behaviour applies to unknown field names (e.g. os=Windows returns 0 instead of telling you = is not the operator; the correct operator is :). See Query Syntax for the verified grammar.

Cross-references

Troubleshooting

Symptom → cause → fix

API Reference

HTTP status codes in detail

Webhook Payload

Outbound webhook shape and retry behaviour

Vitals States

All Vitals state values

Audit Log Events

What gets recorded

Support

Escalate persistent errors

ThreatAware Protect

Getting Started

Inventory

Tags & Logic Engine

Vitals & Issues

Action Center

Integrations

Reporting

Access & Admin

Reference

Trust & Security

API HTTP status codes

Sync errors (Integrations)

Action errors

Integration auth errors

Platform error states

In-product query parsing

Cross-references

Troubleshooting

API Reference

Webhook Payload

Vitals States

Audit Log Events

Support

​API HTTP status codes

​Sync errors (Integrations)

​Action errors

​Integration auth errors

​Platform error states

​In-product query parsing

​Cross-references

Troubleshooting

API Reference

Webhook Payload

Vitals States

Audit Log Events

Support

API HTTP status codes

Sync errors (Integrations)

Action errors

Integration auth errors

Platform error states

In-product query parsing

Cross-references