> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & states

> Error responses and the platform states that can stop a Guard API call.

## Error envelope

Errors return a non-200 status with this shape:

```json theme={null}
{
  "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](/en/v1.2/api/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](/en/v1.2/admin/api-keys).                                                                     |
| **Kill Switch active**        | An admin activated the [Kill Switch](/en/v1.2/admin/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](/en/v1.2/api/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.

<Note>
  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`.
</Note>

## 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](/en/v1.2/admin/monitoring-opticon) (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

<Steps>
  <Step title="Check HTTP status">200 = evaluated; 4xx/5xx = not evaluated.</Step>
  <Step title="On 200, branch on `action`">PASS / MASK / BLOCK — see [Response format](/en/v1.2/api/response-format).</Step>
  <Step title="On error, inspect `error.details`">Fail closed (block) or open (allow) per your risk posture.</Step>
</Steps>