Skip to main content

​
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:
StateWhat happenedWhat to do
Auth failureKey missing, not found, or revoked.Returns 401 (above).
API not foundNo API matches the key.Check you’re using the right key.
API key inactiveAn admin toggled the key off.Re-enable or use another key. See Manage API keys.
Kill Switch activeAn admin activated the Kill Switch on the org, project, or Guardian.Traffic is intentionally blocked; wait until it is deactivated.
Unsupported processTypeThe value isn’t one the Guardian declared.Use a supported process type; the error message lists them.
Input Type not enabledA 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 exceededText length or file size over the Guardian’s limit.Reduce the payload.
Guardian failureThe 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

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.