Skip to main content

​
Error envelope

Errors return a non-200 status with this shape:
This page covers errors on the synchronous Guard API. For the S3 de-identification batch error contract — intake-time HTTP errors vs. processing-time job failures (error.code) — see Batch errors.

​
Fail-closed: an error is never a clean result

The Guard API is fail-closed. A request the Guardian cannot fully analyze returns an HTTP error — it is never downgraded to a 200 with empty detections. So a PASS always means “analyzed, nothing detected,” and an outage can’t quietly turn into a bypass. Guardian-side failures come in two classes:
  • Input errors (4xx) — the input itself can’t be processed (e.g. a corrupt file whose contents can’t be extracted).
  • Processing failures (5xx) — the input is fine but the Guardian couldn’t finish (e.g. an AI model call failed or timed out).
A partial failure (some of several model calls fail) is treated as a whole-request error, because a partial result is indistinguishable from “nothing detected.”

​
Trace-recording failures (Fail-Closed projects)

Since v1.3, a project can set its Opticon Fail-Safe policy to Fail-Closed: if the request was analyzed but its trace ultimately can’t be recorded, the request is demoted to BLOCK instead of passing unrecorded. Recording attempts are bounded (time and retry ceilings), so an Opticon outage shows up as added latency and blocks — never a hanging response. On the default Fail-Open policy, nothing changes for callers: the verdict is returned as-is and only the record is lost.

​
Authentication — 401

A missing, invalid, or revoked API key returns HTTP 401 with error.details: "API_KEY_INVALID". Check the X-Starfort-Guard-Api-Key header and that the key is still active. See Authentication.

​
States that stop a call

A call first passes through the gateway’s pre-validation (authentication, key state, Kill Switch, processType). Content-level inspection policy — unsupported-file handling and the inspection limits (text length, file size) — is enforced at a single point, the Guardian, starting with v1.4: the same rules apply not just to top-level inputs but to text extracted from files and to archive members. These are the states that can stop a call, in the order they’re checked: The inactive and Kill Switch responses deliberately do not reveal where the block came from (org / project / Guardian) — this prevents resource enumeration. The location is recorded only in the audit log.
Exact error.code values and HTTP status for these states can vary by deployment; the 401 auth response above is the stable contract. Branch on HTTP status first, then on error.details.

​
What gets traced

Failures after the key is confirmed active — unsupported processType, Input Type mismatch, limit violations, and Guardian failures — are recorded as Opticon traces (error info + input metadata, but not the message body or file contents). The earlier states — auth failure, API not found, inactive key, and Kill Switch — are not traced; they’re security/governance events handled in separate logs.
1

Check HTTP status

200 = evaluated; 4xx/5xx = not evaluated.
2

On 200, branch on `action`

PASS / MASK / BLOCK — see Response format.
3

On error, inspect `error.details`

Fail closed (block) or open (allow) per your risk posture.