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

# Batch errors

> The Starfort batch de-identification error contract: intake-time HTTP errors and processing-time job failures via error.code (Starfort v1.4 docs)

Batch errors split into two layers by when they occur:

* **Request / intake time** — intake is rejected and **no job is created**. Returned immediately as an HTTP error response.
* **Processing time** — intake succeeded, but the inspection couldn't be completed, so the job finalizes as `FAILED`. The reason is provided in the [job status](/en/v1.4/api/batch/jobs) response's `error` (`code` / `message` / `details`).

**BLOCK is not an error** — it's a normal verdict from a completed inspection, returned as `COMPLETED` + `action: "BLOCK"`. See the [batch overview](/en/v1.4/api/batch/overview).

## Request / intake time (HTTP responses)

The error envelope is the same as the inline [Guard API's error format](/en/v1.4/api/errors):

```json theme={"dark"}
{
  "ok": false,
  "error": {
    "code": "S3_TARGET_NOT_ALLOWED",
    "message": "tgt_s3_url is outside the allowed write scope",
    "details": "connection 's3-prod' allows WRITE on s3://your-bucket/deidentified/*"
  }
}
```

| HTTP | `error.code`                   | Situation                                                                                                                     |
| ---- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| 401  | `UNAUTHORIZED`                 | API key missing or invalid                                                                                                    |
| 403  | (active-state codes)           | Deactivated, or a [Kill Switch](/en/v1.4/admin/kill-switch) is active — while it's on, both creation and queries are rejected |
| 400  | `BAD_REQUEST`                  | Malformed request — a bad URL format, an unsupported `process_type`, and so on                                                |
| 400  | `S3_CONNECTION_NOT_CONFIGURED` | No [Storage Connection](/en/v1.4/api/batch/storage-connection) registered on the project                                      |
| 400  | `S3_TARGET_NOT_ALLOWED`        | `src` / `tgt` falls outside the allowed scope (bucket · path · read/write mode)                                               |
| 404  | `NOT_FOUND`                    | Querying a job ID that doesn't exist                                                                                          |
| 502  | `BAD_GATEWAY`                  | A transient internal Starfort failure — retry                                                                                 |

## Processing-time failures (job `error.code`)

Returned in the job status response as `status: "FAILED"` with an `error.code`. A failed job writes nothing to `tgt`.

| `error.code`                                 | Situation                                                                                          |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SRC_FETCH_FAILED`                           | Couldn't read the source — object missing, access denied, and so on                                |
| `SRC_UNSUPPORTED_TYPE`                       | Unsupported format, or extension/content mismatch (a disguised file)                               |
| `FILE_TOO_LARGE` / `TEXT_TOO_LONG`           | File-size · text-length [limit](/en/v1.4/api/batch/outputs-and-limits) exceeded                    |
| `GUARDIAN_CALL_FAILED` / `GUARDIAN_REJECTED` | Analysis-engine processing failure — details in `details`                                          |
| `TGT_WRITE_FAILED`                           | Couldn't write the output — write permission, capacity, and so on                                  |
| `KILL_SWITCH_ACTIVATED`                      | A Kill Switch fired after intake — waiting and in-progress jobs finalized as failed with no output |
| `JOB_EXPIRED`                                | Not completed within the retry budget — resubmit                                                   |

## Recommended handling

<Steps>
  <Step title="Check the HTTP status on job creation">202 = accepted (keep the `job_id`); 4xx/5xx = no job created — branch on `error.code` to correct the request or retry.</Step>
  <Step title="Branch on `status` when polling">`COMPLETED` = check the verdict (`action`); `FAILED` = branch on `error.code`.</Step>
  <Step title="Handle failures">For the `SRC_*` / `S3_*` family, fix the bucket, permissions, or file, then resubmit. For `GUARDIAN_*` / `JOB_EXPIRED` / 502, retry (resubmit) with backoff.</Step>
</Steps>