Errors & states - Starfort

Error envelope

Errors return a non-200 status with this shape:

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials (getApiGuardGate)",
    "details": "API_KEY_INVALID"
  }
}

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.”

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 passes through pre-validation before the Guardian runs. These are the states that can stop it, in the order they’re checked:

State	What happened	What to do
Auth failure	Key missing, not found, or revoked.	Returns 401 (above).
API not found	No API matches the key.	Check you’re using the right key.
API key inactive	An admin toggled the key off.	Re-enable or use another key. See Manage API keys.
Kill Switch active	An admin activated the Kill Switch on the org, project, or Guardian.	Traffic is intentionally blocked; wait until it is deactivated.
Unsupported `processType`	The value isn’t one the Guardian declared.	Use a supported process type; the error message lists them.
Input Type not enabled	A content part’s type isn’t enabled on the Guardian.	Enable it on the Guardian, or don’t send that part. (File parts only fail here under BLOCK handling — see Multimodal.)
Limit exceeded	Text length or file size over the Guardian’s limit.	Reduce the payload.
Guardian failure	The Guardian endpoint was unreachable or errored.	Retry with backoff.

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.

Recommended handling

Check HTTP status

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

On 200, branch on `action`

PASS / MASK / BLOCK — see Response format.

On error, inspect `error.details`

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

​Error envelope

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

​Authentication — 401

​States that stop a call

​What gets traced

​Recommended handling

Error envelope

Fail-closed: an error is never a clean result

Authentication — 401

States that stop a call

What gets traced

Recommended handling